Docker Compose

Rules

docker_compose_binary
docker_compose_test
docker_compose_toolchain
docker_compose_yaml

docker_compose_binary

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

docker_compose_binary(name, images, yaml)

Creates a runnable target for invoking docker-compose with a generated configuration.

This rule consumes a docker_compose_yaml target and produces an executable that:

Loads container images into Docker using the specified loader targets
Runs docker-compose -f <yaml> <args...> forwarding all command-line arguments

Use this rule when you need to interactively manage docker-compose services (e.g. bazel run :compose -- up -d, bazel run :compose -- down).

Supported image loader types:

Loader	Source
oci_load	rules_oci
image_load	rules_img

Example:

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

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

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

docker_compose_binary(
    name = "compose",
    yaml = ":compose_yaml",
    images = [":my_service.load"],
)

Then run with:

bazel run :compose -- up -d
bazel run :compose -- down
bazel run :compose -- ps

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
images	Image loader targets that provide the container images for the docker-compose services. Each image will be loaded into Docker before docker-compose is invoked. See the rule documentation for supported loader types.	List of labels	optional	`[]`
yaml	A `docker_compose_yaml` target providing the merged docker-compose configuration.	Label	required

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:

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

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

Supported image loader types:

Loader	Source
oci_load	rules_oci
image_load	rules_img

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

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	Additional runtime dependencies for the test.	List of labels	optional	`[]`
delay	Seconds to wait after containers are running before executing the test. Useful for services that need initialization time beyond their health checks.	Integer	optional	`1`
env	Dictionary of strings; values are subject to `$(location)` and "Make variable" substitution	Dictionary: String -> String	optional	`{}`
env_inherit	Specifies additional environment variables to inherit from the external environment when the test is executed by `bazel test`.	List of strings	optional	`[]`
images	Image loader targets that provide the container images for the docker-compose services. Each image will be loaded into Docker before `docker-compose up` is called. See the rule documentation for supported loader types.	List of labels	optional	`[]`
test	The test binary to execute after containers are running. The binary will receive arguments from `test_args`.	Label	optional	`None`
test_args	Arguments to pass to the test binary.	List of strings	optional	`[]`
yamls	One or more docker-compose YAML files defining the services to run. Files are merged using `docker-compose config`.	List of labels	optional	`[]`

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:

Mode	Description
`oci`	Uses the OCI manifest digest directly from the image's index.json. Use this when images are pushed to an OCI-compliant registry.
`docker-legacy`	Uses the config blob digest from the OCI manifest. This is the image ID that Docker reports after `docker load` when using legacy storage (without containerd). Use this for Linux CI runners like GitHub Actions.
`docker-containerd`	Converts the OCI manifest to Docker V2 Schema 2 format and computes the manifest digest. This is the image ID that Docker reports after `docker load` when using containerd storage. Use this for Docker Desktop or Docker Engine with containerd enabled.

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

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
digest_mode	Controls how image digests are computed for lock files. See the rule documentation for details on available modes. Defaults to the value of `--@rules_docker_compose//docker_compose/settings:toolchain_default_digest_mode`.	String	optional	`""`
docker_compose	The docker-compose executable.	Label	required
version	The version of docker-compose.	String	required

docker_compose_yaml

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

docker_compose_yaml(name, data, out, config, images, yamls)

Merges docker-compose configurations and validates image references.

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

At least one of yamls or config must be provided. When both are given, they are merged together using docker-compose config (the config JSON is applied on top of the YAML files).

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:

Loader	Source
oci_load	rules_oci
image_load	rules_img

Example with YAML files:

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"],
)

Example with inline Starlark config:

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

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

docker_compose_yaml(
    name = "compose",
    config = docker_compose_config(
        services = {
            "web": {
                "image": "my-app/nginx:latest",
                "ports": ["8080:80"],
            },
        },
    ),
    images = [":nginx.load"],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	Additional files referenced by the docker-compose configuration (e.g. env_file, config files, secret files, bind-mount sources). These are made available during the merge action and propagated to consuming rules for runtime availability.	List of labels	optional	`[]`
out	Optional output filename for the merged docker-compose YAML. Defaults to `{name}/docker-compose.yaml`.	Label; nonconfigurable	optional	`None`
config	A JSON-encoded docker-compose configuration string. Use `docker_compose_config()` to produce this value from structured Starlark dicts. Can be used alone or combined with `yamls`.	String	optional	`""`
images	Image loader targets that provide the container images referenced in the configuration. Each image referenced in the docker-compose config must have a corresponding loader target. See the rule documentation for supported loader types.	List of labels	optional	`[]`
yamls	One or more docker-compose YAML files to merge. Files are merged in order using `docker-compose config`. At least one of `yamls` or `config` must be provided.	List of labels	optional	`[]`

docker_compose_config

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

docker_compose_config(services, networks, volumes, configs, secrets)

Encode a docker-compose configuration as a JSON string.

Parameters mirror the top-level keys of the Compose Specification. The returned string is suitable for passing to the config attribute of docker_compose_yaml.

PARAMETERS

Name	Description	Default Value
services	A dict mapping service names to their configuration dicts. Each value follows the Compose `services.<name>` schema (image, ports, environment, volumes, depends_on, etc.).	`{}`
networks	A dict mapping network names to their configuration dicts. Follows the Compose `networks.<name>` schema.	`{}`
volumes	A dict mapping volume names to their configuration dicts. Follows the Compose `volumes.<name>` schema.	`{}`
configs	A dict mapping config names to their configuration dicts. Follows the Compose `configs.<name>` schema.	`{}`
secrets	A dict mapping secret names to their configuration dicts. Follows the Compose `secrets.<name>` schema.	`{}`

RETURNS

A JSON-encoded string representing the docker-compose configuration.