Docker Compose

Rules

• docker_compose_test
• docker_compose_toolchain
• docker_compose_yaml

docker_compose_test

load("@rules_docker_compose//docker_compose:defs.bzl", "docker_compose_test")

docker_compose_test(name, data, delay, env, env_inherit, images, test, test_args, yamls)

Runs a test with docker-compose services.

This rule starts docker-compose services, waits for them to be ready, runs a test binary, and then tears down the services. The test lifecycle is:

1. Loading container images into Docker using the specified loader targets
2. Starting services with docker-compose up
3. Waiting for containers to be running (with health checks)
4. Verifying image digests match the expected values from the lock file
5. Running the test binary with optional arguments
6. Cleaning up with docker-compose down

The test requires network access and Docker to be available on the host.

Supported image loader types:

Example:

load("@rules_docker_compose//docker_compose:docker_compose_test.bzl", "docker_compose_test")
load("@rules_oci//oci:defs.bzl", "oci_load")

oci_load(
    name = "my_service.load",
    image = ":my_service",
    repo_tags = ["my-service:latest"],
)

docker_compose_test(
    name = "integration_test",
    yamls = ["docker-compose.yaml"],
    images = [":my_service.load"],
    test = ":my_test_binary",
    test_args = ["-host", "localhost:8080"],
    delay = 2,  # Wait 2 seconds after containers start
)

ATTRIBUTES

docker_compose_toolchain

load("@rules_docker_compose//docker_compose:defs.bzl", "docker_compose_toolchain")

docker_compose_toolchain(name, digest_mode, docker_compose, version)

A toolchain for providing Docker-Compose to Bazel rules.

The digest_mode attribute controls how image digests are computed for lock files:

See the OCI Image Manifest spec and the Docker V2 Schema 2 spec.

Example:

load("@rules_docker_compose//docker_compose:docker_compose_toolchain.bzl", "docker_compose_toolchain")

filegroup(
    name = "docker_compose_bin",
    srcs = ["docker_compose/docker_compose.exe"],
    # Note that additional runfiles associated with a hermetic archive
    # of docker_compose should be associated with the target passed to the
    # `docker_compose` attribute.
    data = glob(["docker_compose/**"]),
)

docker_compose_toolchain(
    name = "docker_compose_toolchain",
    docker_compose = ":docker_compose_bin",
    visibility = ["//visibility:public"],
)

For users looking to use a system install of Docker-Compose, a shell/batch script should be added that points to the system install.

Example or non-hermetic toolchain:

docker_compose.sh

#!/usr/bin/env bash
set -euo pipefail
exec /usr/bin/docker_compose $@

docker_compose.bat

@ECHO OFF
C:\Program Files\Docker\Docker\resources\docker-compose.exe %*
set EXITCODE=%ERRORLEVEL%
exit /b %EXITCODE%

load("@rules_docker_compose//docker_compose:docker_compose_toolchain.bzl", "docker_compose_toolchain")

filegroup(
    name = "docker_compose_bin",
    srcs = select({
        "@platforms//os:windows": ["docker_compose.bat"],
        "//conditions:default": ["docker_compose.sh"],
    }),
)

docker_compose_toolchain(
    name = "docker_compose_toolchain",
    docker_compose = ":docker_compose_bin",
    visibility = ["//visibility:public"],
)

ATTRIBUTES

docker_compose_yaml

load("@rules_docker_compose//docker_compose:defs.bzl", "docker_compose_yaml")

docker_compose_yaml(name, out, images, yamls)

Merges multiple docker-compose YAML files and validates image references.

This rule uses docker-compose config to merge one or more docker-compose YAML files into a single, canonical configuration. It also validates that all images referenced in the configuration have corresponding loader targets specified in the images attribute.

A lock file is generated containing a mapping of image tags to their content digests, which can be used to verify that the correct images are loaded at runtime.

Supported image loader types:

Example:

load("@rules_docker_compose//docker_compose:docker_compose_yaml.bzl", "docker_compose_yaml")
load("@rules_oci//oci:defs.bzl", "oci_load")

oci_load(
    name = "my_image.load",
    image = ":my_image",
    repo_tags = ["my-app:latest"],
)

docker_compose_yaml(
    name = "compose",
    yamls = ["docker-compose.yaml"],
    images = [":my_image.load"],
)

ATTRIBUTES