### Initialize and Start Compose Services with Go SDK

Source: https://github.com/docker/compose/blob/main/docs/sdk.md

Demonstrates the core workflow of creating a Compose service instance, loading a project from a Compose file, and starting services. This example shows how to initialize the Docker CLI, create a NewComposeService, load project configuration, and execute the Up operation to start containerized 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)
}
```

--------------------------------

### CLI Command: docker compose start

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_start.md

Starts existing containers for a service. This command allows for options like performing a dry run, waiting for services to become healthy, and setting a timeout for the waiting period.

```APIDOC
## CLI Command: docker compose start

### Description
Starts existing containers for a service.

### Method
CLI Command

### Endpoint
docker compose start

### Parameters
#### Command Options
- **--dry-run** (bool) - Optional - Execute command in dry run mode.
- **--wait** (bool) - Optional - Wait for services to be running|healthy. Implies detached mode.
- **--wait-timeout** (int) - Optional - Maximum duration in seconds to wait for the project to be running|healthy.

### Request Example
```bash
docker compose start --wait --wait-timeout 60
```

### Response
#### Success Response (0)
The command exits with a status code of 0 on success. Containers are started.

#### Response Example
```text
[No direct JSON/text output for successful start, typically just success exit code]
```
```

--------------------------------

### Info Message Example

Source: https://github.com/docker/compose/blob/main/docs/extension.md

An example of an info message sent from a provider to Compose to report status updates. Compose renders this as the service state.

```json
{ "type": "info", "message": "preparing mysql ..." }
```

--------------------------------

### Run a one-time command against a service

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_run.md

Starts the specified service and executes a one-time command, overriding the service's default command.

```console
$ docker compose run web bash
```

--------------------------------

### Provider Command Execution Example

Source: https://github.com/docker/compose/blob/main/docs/extension.md

This console command demonstrates how Docker Compose invokes a provider's `compose up` command. It passes project name, service name, and options as flags to the provider executable.

```console
awesomecloud compose --project-name <NAME> up --type=mysql --size=256 "database"
```

--------------------------------

### Run a command without starting linked services

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_run.md

Executes a command for a service without automatically starting any linked containers.

```console
$ docker compose run --no-deps web python manage.py shell
```

--------------------------------

### Raw Environment Variable Injection (rawsetenv)

Source: https://github.com/docker/compose/blob/main/docs/extension.md

Example of a 'rawsetenv' JSON message from a provider, injecting an environment variable as-is without prefixing.

```json
{"type": "rawsetenv", "message": "SECRET_KEY=xxx"}
```

--------------------------------

### docker compose Command Line Interface

Source: https://github.com/docker/compose/blob/main/docs/reference/compose.md

This section provides an overview of the `docker compose` command, its various options, and examples demonstrating how to use them for defining and running multi-container Docker applications.

```APIDOC
## CLI Command: docker compose

### Description
The `docker compose` command is a powerful tool for defining and running multi-container Docker applications. This documentation outlines the various command-line options available to customize its behavior and provides practical examples of its usage.

### Method
CLI Command

### Endpoint
`docker compose`

### Parameters
#### Command-line Options
- **--all-resources** (`bool`) - Optional - Include all resources, even those not used by services
- **--ansi** (`string`) - Optional - Control when to print ANSI control characters ("never"|"always"|"auto")
- **--compatibility** (`bool`) - Optional - Run compose in backward compatibility mode
- **--dry-run** (`bool`) - Optional - Execute command in dry run mode
- **--env-file** (`stringArray`) - Optional - Specify an alternate environment file
- **-f**, **--file** (`stringArray`) - Optional - Compose configuration files. When multiple files are supplied, Compose combines them in order, with subsequent files overriding or adding to predecessors.
- **--parallel** (`int`) - Optional - Control max parallelism, -1 for unlimited
- **--profile** (`stringArray`) - Optional - Specify a profile to enable
- **--progress** (`string`) - Optional - Set type of progress output (auto, tty, plain, json, quiet)
- **--project-directory** (`string`) - Optional - Specify an alternate working directory (default: the path of the, first specified, Compose file)
- **-p**, **--project-name** (`string`) - Optional - Project name

### Request Example
```console
# Example: Specifying multiple Compose files
$ docker compose -f compose.yaml -f compose.admin.yaml run backup_db
```
```yaml
# Example: compose.yaml content
services:
  webapp:
    image: examples/web
    ports:
      - "8000:8000"
    volumes:
      - "/data"
```
```yaml
# Example: compose.admin.yaml content (overrides/adds to compose.yaml)
services:
  webapp:
    build: .
    environment:
      - DEBUG=1
```
```console
# Example: Specifying a path to a single Compose file
$ docker compose -f ~/sandbox/rails/compose.yaml pull db
```

### Response
#### Success Response
The `docker compose` command typically outputs logs, status messages, or the result of the executed sub-command to the console. There is no standardized JSON or structured API response.

#### Response Example
```console
# Example output for 'docker compose pull db'
Pulling db (postgres:latest)...
latest: Pulling from library/postgres
... (image pull progress) ...
Digest: sha256:...
Status: Downloaded newer image for postgres:latest
```
```console
# Example output for 'docker compose run backup_db'
Starting backup_db ... done
... (application specific output) ...
```
```

--------------------------------

### Set Raw Environment Variable

Source: https://github.com/docker/compose/blob/main/docs/extension.md

Example of a 'rawsetenv' message, similar to 'setenv', but the variable is injected without any prefix. This is useful when applications require exact variable names.

```json
{ "rawsetenv": "SECRET_KEY=xxx" }
```

--------------------------------

### GET /docker/compose/version

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_version.md

Retrieves the version information for Docker Compose, with options to format the output or show only the version number.

```APIDOC
## GET /docker/compose/version

### Description
Retrieves the version information for Docker Compose.

### Method
GET

### Endpoint
/docker/compose/version

### Parameters
#### Query Parameters
- **dry-run** (bool) - Optional - Execute command in dry run mode
- **format** (string) - Optional - Format the output. Values: [pretty | json]. (Default: pretty)
- **short** (bool) - Optional - Shows only Compose's version number
```

--------------------------------

### Prefixed Environment Variable Injection (setenv)

Source: https://github.com/docker/compose/blob/main/docs/extension.md

Example of a 'setenv' JSON message from a provider, resulting in a prefixed environment variable for dependent services.

```json
{"type": "setenv", "message": "URL=https://awesomecloud.com/db:1234"}
```

--------------------------------

### Example Compose Service with Provider

Source: https://github.com/docker/compose/blob/main/docs/extension.md

This YAML snippet shows how to define a service in Docker Compose that uses an external provider for management. The `provider.type` specifies the external tool, and `provider.options` configure the specific service instance.

```yaml
  database:
    provider:
      type: awesomecloud
      options:
        type: mysql
        size: 256
        name: myAwesomeCloudDB
```

--------------------------------

### GET /docker/compose/events

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_events.md

Stream container events for all containers within a Docker Compose project. This command allows monitoring real-time activities such as container creation, start, stop, and destruction. Optionally, output can be formatted as a stream of JSON objects.

```APIDOC
## GET /docker/compose/events

### Description
Stream container events for every container in a Docker Compose project. This command allows monitoring real-time activities such as container creation, start, stop, and destruction. When the `--json` flag is used, events are outputted as a stream of JSON objects, one per line.

### Method
GET

### Endpoint
/docker/compose/events

### Parameters
#### Query Parameters
- **dry-run** (boolean) - Optional - Execute command in dry run mode.
- **json** (boolean) - Optional - Output events as a stream of JSON objects.
- **since** (string) - Optional - Show all events created since a specified timestamp.
- **until** (string) - Optional - Stream events until a specified timestamp.

### Request Example
```bash
docker compose events --json --since "2023-01-01T00:00:00Z"
```

### Response
#### Success Response (200)
- **time** (string) - The timestamp when the event occurred.
- **type** (string) - The type of the object related to the event (e.g., "container").
- **action** (string) - The action performed on the object (e.g., "create", "start", "stop").
- **id** (string) - The unique identifier of the object.
- **service** (string) - The name of the Docker Compose service associated with the event.
- **attributes** (object) - A dictionary of additional attributes for the event.
    - **name** (string) - The name of the container.
    - **image** (string) - The image used by the container.

#### Response Example
```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"
    }
}
```
```

--------------------------------

### Stream Container Events in JSON Format

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_events.md

Example of the JSON object structure emitted by the docker compose events --json command. Each object represents a single container action such as create or start, including timestamps and service attributes.

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

--------------------------------

### Run an interactive command for a linked service

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_run.md

Starts linked services if they are stopped and then executes an interactive command within the specified service container.

```console
$ docker compose run db psql -h db -U docker
```

--------------------------------

### Get Provider Metadata

Source: https://github.com/docker/compose/blob/main/docs/extension.md

Invoke the metadata subcommand to retrieve information about the parameters accepted by the up and down commands. This is a console command.

```console
awesomecloud compose metadata
```

--------------------------------

### GET docker compose bridge transformations list

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_bridge_transformations_list.md

Retrieves a list of all available transformations within the Docker Compose bridge environment. Supports filtering output format and quiet mode.

```APIDOC
## GET docker compose bridge transformations list

### Description
List available transformations

### Method
GET

### Endpoint
docker compose bridge transformations list

### Parameters
#### Query Parameters
- **dry-run** (bool) - Optional - Execute command in dry run mode
- **format** (string) - Optional - Format the output. Values: [table | json]. Default: table
- **quiet** (bool) - Optional - Only display transformer names

### Request Example
docker compose bridge transformations list --format json

### Response
#### Success Response (200)
- **transformations** (array) - A list of available transformation objects.

#### Response Example
[
  {
    "name": "example-transform",
    "description": "An example transformation"
  }
]
```

--------------------------------

### POST /docker/compose/kill

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_kill.md

Forces running containers to stop by sending a `SIGKILL` signal. Optionally the signal can be passed, for example: `$ docker compose kill -s SIGINT`

```APIDOC
## POST /docker/compose/kill

### Description
Forces running containers to stop by sending a `SIGKILL` signal. Optionally the signal can be passed, for example: `$ docker compose kill -s SIGINT`

### Method
POST

### Endpoint
/docker/compose/kill

### Parameters
#### Query Parameters
- **dry-run** (boolean) - Optional - Execute command in dry run mode
- **remove-orphans** (boolean) - Optional - Remove containers for services not defined in the Compose file
- **signal** (string) - Optional - SIGNAL to send to the container (Default: SIGKILL)

### Request Example
{
  "dry-run": true,
  "signal": "SIGINT"
}

### Response
#### Success Response (200)
No explicit JSON response body. Command execution typically indicates success via exit code.

#### Response Example
{}
```

--------------------------------

### Format Docker Compose ps Output as JSON

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_ps.md

Use the `--format json` flag to get container information as JSON Lines. This is useful for programmatic processing with tools like `jq`.

```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"}]}
```

--------------------------------

### Set Environment Variable

Source: https://github.com/docker/compose/blob/main/docs/extension.md

Example of a 'setenv' message used by a plugin to inform Compose about environment variables for dependent services. Compose automatically prefixes these variables with the service name.

```json
{ "setenv": "URL=http://cloud.com/abcd:1234" }
```

--------------------------------

### Docker Compose YAML service definition

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_pull.md

Example compose.yaml file defining multiple services including a postgres database and a Rails web application. Demonstrates service image configuration, build context, volumes, ports, and service dependencies used with docker compose pull command.

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

--------------------------------

### Customize Compose Service with Options in Go

Source: https://github.com/docker/compose/blob/main/docs/sdk.md

Shows how to customize the Compose SDK behavior using optional compose.Option parameters. Demonstrates configuration of I/O streams, concurrency limits, dry-run mode, and prompt handling for advanced integration scenarios including CLI tools, web services, and automation scripts.

```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
    )
```

--------------------------------

### Execute Docker Compose Push with Options

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_push.md

Demonstrates the use of the push command with various flags such as ignoring failures and including dependencies. These options provide more control over the image upload lifecycle.

```bash
docker compose push --ignore-push-failures --include-deps --quiet
```

--------------------------------

### Build Docker Compose

Source: https://github.com/docker/compose/blob/main/CLAUDE.md

Run this command to build the Docker Compose project.

```bash
make build
```

--------------------------------

### Run GolangCI-Lint

Source: https://github.com/docker/compose/blob/main/CLAUDE.md

Execute the golangci-lint linter to check code quality and style. Ensure all reported issues are fixed before committing.

```bash
golangci-lint run --build-tags "e2e" ./...
```

--------------------------------

### Run Unit Tests

Source: https://github.com/docker/compose/blob/main/CLAUDE.md

Execute unit tests for the Go packages within the Docker Compose project.

```bash
go test ./pkg/...
```

--------------------------------

### Lint via Docker

Source: https://github.com/docker/compose/blob/main/CLAUDE.md

Run the linter using Docker, which uses a version pinned in the Dockerfile.

```bash
docker buildx bake lint
```

--------------------------------

### Run All Tests

Source: https://github.com/docker/compose/blob/main/CLAUDE.md

Execute all tests for the Docker Compose project.

```bash
make test
```

--------------------------------

### Display running processes

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_top.md

Use this command to view the process table for all containers managed by the current Compose file.

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

--------------------------------

### Run a command with service ports exposed

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_run.md

Executes a command for a service, ensuring that the service's configured ports are created and mapped to the host.

```console
$ docker compose run --service-ports web python manage.py shell
```

--------------------------------

### Run a command with manual port mapping

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_run.md

Executes a command for a service while manually publishing specific ports from the container to the host.

```console
$ docker compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell
```

--------------------------------

### Pretty-print JSON Output with jq

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_ps.md

Pipe the JSON output of `docker compose ps --format json` to the `jq` utility for pretty-printing and easier readability.

```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"
    }
  ]
}
```

--------------------------------

### List All Containers (Running and Stopped) with docker compose ps --all

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_ps.md

Includes stopped containers in the output when the `--all` flag is used. This provides a comprehensive view of all containers associated with the Compose project.

```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)
```

--------------------------------

### Define Application Services with Docker Compose YAML

Source: https://github.com/docker/compose/blob/main/README.md

This YAML configuration demonstrates how to define services for a multi-container application using Docker Compose. It includes a 'web' service that builds from the current directory, maps a port, and mounts a volume, and a 'redis' service that uses a pre-built image. This file, typically named `compose.yaml`, is central to orchestrating your application with `docker compose up`.

```yaml
services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - .:/code
  redis:
    image: redis
```

--------------------------------

### Pull specific service image with docker compose

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_pull.md

Pulls the image for a specific service defined in compose.yaml file. In this example, the postgres image associated with the 'db' service is pulled. The command executes in the same directory as the compose.yaml file and downloads all image layers.

```bash
docker compose pull db
```

--------------------------------

### List Running Containers with docker compose ps

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_ps.md

Shows running containers for a Compose project, including their name, image, command, service, creation time, status, and 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
```

--------------------------------

### Run End-to-End Tests

Source: https://github.com/docker/compose/blob/main/CLAUDE.md

Execute end-to-end tests for the Docker Compose project using the 'e2e' build tag.

```bash
go test -tags e2e ./pkg/e2e/ -run TestName
```

--------------------------------

### Run Single Unit Test

Source: https://github.com/docker/compose/blob/main/CLAUDE.md

Execute a specific unit test function in the Docker Compose project.

```bash
go test ./pkg/compose/ -run TestFunctionName
```

--------------------------------

### docker compose stats

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_stats.md

Display a live stream of container(s) resource usage statistics.

```APIDOC
## docker compose stats

### Description
Display a live stream of container(s) resource usage statistics.

### Method
Not Applicable (CLI Command)

### Endpoint
Not Applicable (CLI Command)

### Options
#### Query Parameters
- **-a, --all** (bool) - Optional - Show all containers (default shows just running)
- **--dry-run** (bool) - Optional - Execute command in dry run mode
- **--format** (string) - Optional - Format output using a custom template. Options include 'table', 'table TEMPLATE', 'json', or 'TEMPLATE'. Refer to https://docs.docker.com/engine/cli/formatting/ for more information.
- **--no-stream** (bool) - Optional - Disable streaming stats and only pull the first result
- **--no-trunc** (bool) - Optional - Do not truncate output

### Request Example
```bash
docker compose stats --all --format json
```

### Response
#### Success Response (200)
- **Output** (string) - Formatted container resource usage statistics based on the specified format.

#### Response Example
```json
{
  "container_id": "example_container_id",
  "name": "example_container_name",
  "cpu_usage": 123456789,
  "memory_usage": 987654321,
  "network_rx": 112233,
  "network_tx": 445566,
  "disk_io_read": 778899,
  "disk_io_write": 112233
}
```
```

--------------------------------

### Execute Docker Compose with multiple configuration files

Source: https://github.com/docker/compose/blob/main/docs/reference/compose.md

This command demonstrates how to use the `-f` flag multiple times to specify several Docker Compose configuration files. When multiple files are provided, Compose combines them, with subsequent files overriding or adding to the definitions from previous ones. This allows for modular and layered service configurations.

```console
$ docker compose -f compose.yaml -f compose.admin.yaml run backup_db
```

--------------------------------

### CLI Command: docker compose images

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_images.md

Lists images used by containers managed by Docker Compose, providing details about their IDs, names, tags, and sizes.

```APIDOC
## CLI Command: docker compose images

### Description
List images used by the created containers.

### Method
CLI Command

### Endpoint
`docker compose images`

### Options
- **--dry-run** (bool) - Optional - Execute command in dry run mode.
- **--format** (string) - Optional - Default: `table` - Format the output. Values: [table | json].
- **-q, --quiet** (bool) - Optional - Only display IDs.

### Command Example
```bash
docker compose images --format json
```

### Output
#### Success Output (0)
The command outputs a list of images used by the services defined in the `docker-compose.yml` file. The format depends on the `--format` option.

#### Output Example
```json
[
  {
    "ID": "sha256:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    "Name": "my-app_web",
    "Tag": "latest",
    "Size": "123MB"
  },
  {
    "ID": "sha256:b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
    "Name": "my-app_db",
    "Tag": "1.0",
    "Size": "50MB"
  }
]
```
```

--------------------------------

### docker compose build

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_build.md

Build or rebuild services in a Docker Compose project. Services are built once and tagged by default as project-service. If a service's Dockerfile or build directory contents change, run this command to rebuild the image.

```APIDOC
## docker compose build

### Description
Build or rebuild services defined in a Docker Compose file. Services are built once and then tagged, by default as `project-service`. If the Compose file specifies an image name, the image is tagged with that name, substituting any variables beforehand.

### Command
```
docker compose build [OPTIONS] [SERVICE...]
```

### Options

| Option | Type | Default | Description |
|:-------|:-----|:--------|:------------|
| `--build-arg` | stringArray | | Set build-time variables for services |
| `--builder` | string | | Set builder to use |
| `--check` | bool | | Check build configuration |
| `--dry-run` | bool | | Execute command in dry run mode |
| `-m`, `--memory` | bytes | 0 | Set memory limit for the build container. Not supported by BuildKit. |
| `--no-cache` | bool | | Do not use cache when building the image |
| `--print` | bool | | Print equivalent bake file |
| `--provenance` | string | | Add a provenance attestation |
| `--pull` | bool | | Always attempt to pull a newer version of the image |
| `--push` | bool | | Push service images |
| `-q`, `--quiet` | bool | | Suppress the build output |
| `--sbom` | string | | Add a SBOM attestation |
| `--ssh` | string | | Set SSH authentications used when building service images. (use 'default' for using your default SSH Agent) |
| `--with-dependencies` | bool | | Also build dependencies (transitively) |

### Usage Examples

#### Basic Build
```bash
docker compose build
```

#### Build Specific Service
```bash
docker compose build web
```

#### Build with Build Arguments
```bash
docker compose build --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ')
```

#### Build Without Cache
```bash
docker compose build --no-cache
```

#### Build and Push Images
```bash
docker compose build --push
```

#### Build with Dependencies
```bash
docker compose build --with-dependencies
```

#### Dry Run Mode
```bash
docker compose build --dry-run
```
```

--------------------------------

### Filter Docker Compose ps with --filter status=running

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_ps.md

Use the `--filter status=running` flag as an alternative to `--status=running` to display only containers that are currently in a running state.

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

--------------------------------

### Configure Service Images in Docker Compose YAML

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_push.md

Specifies how to define service images in a YAML file for pushing to different registries. Service1 is configured for a local registry, while Service2 is configured for a Docker Hub repository.

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

--------------------------------

### Run a command and remove container on exit

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_run.md

Executes a command for a service and removes the container upon completion, overriding any restart policy.

```console
$ docker compose run --rm web python manage.py db upgrade
```

--------------------------------

### POST /docker/compose/alpha/publish

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_alpha_publish.md

This endpoint allows users to publish a Docker Compose application to an OCI registry. It supports various configurations, including dry-run execution, specifying the OCI artifact version, resolving image tags to digests, and embedding environment variables within the published artifact.

```APIDOC
## POST /docker/compose/alpha/publish

### Description
This endpoint facilitates the publishing of a Docker Compose application to an OCI registry. It supports various configurations, including dry-run execution, specifying the OCI artifact version, resolving image tags to digests, and embedding environment variables within the published artifact.

### Method
POST

### Endpoint
/docker/compose/alpha/publish

### Parameters
#### Request Body
- **dry_run** (boolean) - Optional - Default: `false` - Execute command in dry run mode without actually publishing.
- **oci_version** (string) - Optional - Default: `auto-determined` - Specifies the OCI image/artifact specification version.
- **resolve_image_digests** (boolean) - Optional - Default: `false` - If true, image tags will be pinned to their digests in the published artifact.
- **with_env** (boolean) - Optional - Default: `false` - If true, environment variables will be included in the published OCI artifact.
- **yes** (boolean) - Optional - Default: `false` - Automatically confirm all prompts without user interaction.

### Request Example
```json
{
  "dry_run": true,
  "resolve_image_digests": true,
  "with_env": false,
  "oci_version": "1.0.0"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the success of the publish operation.
- **artifact_id** (string) - The identifier of the published OCI artifact, if applicable.
- **status** (string) - The status of the publish operation (e.g., "published", "dry-run-successful").

#### Response Example
```json
{
  "message": "Compose application published successfully to OCI registry.",
  "artifact_id": "sha256:a1b2c3d4e5f6...",
  "status": "published"
}
```
```

--------------------------------

### CLI docker compose publish

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_publish.md

The docker compose publish command allows users to publish a compose application to a registry, optionally including referenced images and environment variables.

```APIDOC
## CLI docker compose publish

### Description
Publish a compose application to a registry as an OCI artifact.

### Method
CLI

### Endpoint
docker compose publish [OPTIONS]

### Parameters
#### Query Parameters
- **--app** (boolean) - Optional - Published compose application (includes referenced images)
- **--dry-run** (boolean) - Optional - Execute command in dry run mode
- **--oci-version** (string) - Optional - OCI image/artifact specification version (automatically determined by default)
- **--resolve-image-digests** (boolean) - Optional - Pin image tags to digests
- **--with-env** (boolean) - Optional - Include environment variables in the published OCI artifact
- **--yes, -y** (boolean) - Optional - Assume "yes" as answer to all prompts

### Request Example
docker compose publish --with-env --resolve-image-digests

### Response
#### Success Response (0)
- **status** (string) - Success message or artifact URI

#### Response Example
{
  "status": "Published successfully"
}
```

--------------------------------

### CMD docker compose bridge transformations

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_bridge.md

Command to manage transformation images for the Docker Compose bridge.

```APIDOC
## CMD docker compose bridge transformations

### Description
Manage transformation images.

### Method
CLI

### Endpoint
docker compose bridge transformations

### Parameters
#### Options
- **--dry-run** (bool) - Optional - Execute command in dry run mode

### Request Example
```bash
docker compose bridge transformations
```

### Response
#### Success Response (0)
- **status** (string) - Status of transformation management

#### Response Example
```text
Transformation images managed successfully.
```
```

--------------------------------

### CMD docker compose bridge convert

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_bridge.md

Converts Docker Compose files into Kubernetes manifests, Helm charts, or other models.

```APIDOC
## CMD docker compose bridge convert

### Description
Convert compose files to Kubernetes manifests, Helm charts, or another model.

### Method
CLI

### Endpoint
docker compose bridge convert

### Parameters
#### Options
- **--dry-run** (bool) - Optional - Execute command in dry run mode

### Request Example
```bash
docker compose bridge convert
```

### Response
#### Success Response (0)
- **output** (string) - The converted model output

#### Response Example
```yaml
apiVersion: v1
kind: Service
metadata:
  name: example
```
```

--------------------------------

### docker compose attach

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_attach.md

Attach local standard input, output, and error streams to a service's running container. This command enables interactive communication with a running container in a Docker Compose project.

```APIDOC
## docker compose attach

### Description
Attach local standard input, output, and error streams to a service's running container

### Command
```
docker compose attach [OPTIONS] SERVICE
```

### Options

#### --detach-keys
- **Type**: string
- **Required**: No
- **Description**: Override the key sequence for detaching from a container.

#### --dry-run
- **Type**: bool
- **Required**: No
- **Description**: Execute command in dry run mode

#### --index
- **Type**: int
- **Default**: 0
- **Required**: No
- **Description**: Index of the container if service has multiple replicas.

#### --no-stdin
- **Type**: bool
- **Required**: No
- **Description**: Do not attach STDIN

#### --sig-proxy
- **Type**: bool
- **Default**: true
- **Required**: No
- **Description**: Proxy all received signals to the process
```

--------------------------------

### Define a base webapp service in Docker Compose YAML

Source: https://github.com/docker/compose/blob/main/docs/reference/compose.md

This `compose.yaml` snippet defines a `webapp` service, specifying its image, port mappings, and a volume. It serves as a base configuration that can be extended or overridden by other Compose files when using the multi-file approach.

```yaml
services:
  webapp:
    image: examples/web
    ports:
      - "8000:8000"
    volumes:
      - "/data"
```

--------------------------------

### Filter Docker Compose ps by Running Status

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_ps.md

Use the `--status=running` flag to display only containers that are currently in a running state.

```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 cp

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_cp.md

Copy files/folders between a service container and the local filesystem. It allows for bidirectional transfer and supports specific container indexing.

```APIDOC
## CLI docker compose cp

### Description
Copy files/folders between a service container and the local filesystem

### Method
CLI

### Endpoint
docker compose cp [OPTIONS] SERVICE:SRC_PATH DEST_PATH|- | SRC_PATH|- SERVICE:DEST_PATH

### Parameters
#### Options
- **--all** (bool) - Optional - Include containers created by the run command
- **-a, --archive** (bool) - Optional - Archive mode (copy all uid/gid information)
- **--dry-run** (bool) - Optional - Execute command in dry run mode
- **-L, --follow-link** (bool) - Optional - Always follow symbol link in SRC_PATH
- **--index** (int) - Optional - Index of the container if service has multiple replicas (Default: 0)

### Request Example
docker compose cp web:/var/www/html/index.html ./index.html

### Response
#### Success Response (0)
- **Exit Code** (int) - Returns 0 on successful file transfer

#### Response Example
Successfully copied to /path/to/destination
```

--------------------------------

### docker compose volumes

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_volumes.md

Lists the volumes associated with the current Docker Compose project. It allows for custom formatting and filtering of the output.

```APIDOC
## CLI docker compose volumes

### Description
List volumes defined in the Compose file for the current project.

### Method
CLI COMMAND

### Endpoint
docker compose volumes

### Parameters
#### Options
- **--dry-run** (bool) - Optional - Execute command in dry run mode.
- **--format** (string) - Optional - Format output using a custom template. Options include 'table' (default), 'json', or a Go template.
- **-q, --quiet** (bool) - Optional - Only display volume names.

### Request Example
docker compose volumes --format json

### Response
#### Success Response (200)
- **Name** (string) - The name of the volume.
- **Driver** (string) - The volume driver used.
- **Scope** (string) - The scope of the volume (e.g., local).

#### Response Example
[
  {
    "Name": "my-project_db_data",
    "Driver": "local",
    "Scope": "local",
    "Mountpoint": "/var/lib/docker/volumes/my-project_db_data/_data"
  }
]
```

--------------------------------

### Pull a Docker Compose service image from a specified file path

Source: https://github.com/docker/compose/blob/main/docs/reference/compose.md

This command illustrates using the `-f` flag to point to a `compose.yaml` file located outside the current working directory. It allows Docker Compose commands, such as `pull db`, to operate on a specific configuration file regardless of the current directory.

```console
$ docker compose -f ~/sandbox/rails/compose.yaml pull db
```

--------------------------------

### Override and extend webapp service in Docker Compose YAML

Source: https://github.com/docker/compose/blob/main/docs/reference/compose.md

This `compose.admin.yaml` snippet shows how to modify an existing `webapp` service definition. It adds a build context and an environment variable, demonstrating how subsequent Compose files can override fields or add new configurations to services defined in earlier files.

```yaml
services:
  webapp:
    build: .
    environment:
      - DEBUG=1
```

--------------------------------

### Filter Docker Compose ps by Exited Status

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_ps.md

Use the `--status=exited` flag to display only containers that have exited.

```console
$ docker compose ps --status=exited
NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
example-bar-1   alpine    "/entrypoint.…"   bar        4 seconds ago   exited (0)
```

--------------------------------

### CLI docker compose alpha watch

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_alpha_watch.md

The watch command monitors the build context for a service and automatically rebuilds or refreshes containers when files are updated. This is useful for development workflows requiring immediate feedback.

```APIDOC
## CLI docker compose alpha watch

### Description
Watch build context for service and rebuild/refresh containers when files are updated.

### Method
CLI

### Endpoint
docker compose alpha watch [SERVICE...]

### Parameters
#### Options
- **--dry-run** (flag) - Optional - Execute command in dry run mode
- **--no-up** (flag) - Optional - Do not build & start services before watching
- **--quiet** (flag) - Optional - Hide build output

### Request Example
docker compose alpha watch web-service

### Response
#### Success Response (0)
- **status** (string) - Command execution status

#### Response Example
[Watching for changes...]
```

--------------------------------

### docker compose watch

Source: https://github.com/docker/compose/blob/main/docs/reference/compose_watch.md

Watch build context for service and rebuild/refresh containers when files are updated. This command monitors file changes and automatically triggers container rebuilds, making it ideal for development workflows.

```APIDOC
## docker compose watch

### Description
Watch build context for service and rebuild/refresh containers when files are updated. This command automatically detects file changes and triggers container rebuilds without manual intervention.

### Command
```
docker compose watch [OPTIONS]
```

### Options

| Name | Type | Default | Description |
|:-----|:-----|:--------|:------------|
| `--dry-run` | boolean | - | Execute command in dry run mode without making actual changes |
| `--no-up` | boolean | - | Do not build & start services before watching |
| `--prune` | boolean | `true` | Prune dangling images on rebuild |
| `--quiet` | boolean | - | Hide build output during watch operations |

### Usage Examples

#### Basic Watch
```bash
docker compose watch
```
Starts watching the build context and automatically rebuilds containers when files change.

#### Dry Run Mode
```bash
docker compose watch --dry-run
```
Executes the watch command in dry run mode to preview changes without applying them.

#### Skip Initial Service Startup
```bash
docker compose watch --no-up
```
Watches for file changes without building and starting services initially.

#### Suppress Build Output
```bash
docker compose watch --quiet
```
Watches for file changes and rebuilds containers with build output hidden.

#### Combined Options
```bash
docker compose watch --no-up --quiet --prune
```
Watches for changes without initial startup, hides output, and prunes dangling images on rebuild.
```