The Pain of Building Docker Images in Bulk
As projects transition from monoliths to microservices, the number of Dockerfiles multiplies rapidly. At this point, the image packaging stage turns into a major bottleneck. Sequential docker build commands can choke CI/CD runners for tens of minutes. On top of that, manually managing numerous build-args, version tags, and multi-arch matrices is highly error-prone.
In practice across engineering teams, we typically see three common approaches:
- Approach 1: Bash scripts or background jobs (
&) — Looping through directories to trigger build commands. - Approach 2: Leveraging
docker compose build— Putting the entire build configuration inside adocker-compose.ymlfile. - Approach 3: Deploying Docker Buildx Bake — Using the official BuildKit tool to declare targets via HCL files, enabling parallel execution and aggressive layer cache reuse.
A Practical Comparison of the Three Approaches
1. Bash Scripts / Makefiles
Writing scripts is the first instinct for many developers because it feels familiar and requires no new syntax to learn.
- Pros: Runs immediately on any server equipped with basic Docker CLI.
- Cons: Cannot share cache across independent stages. Running them sequentially is time-consuming. Forcing background execution with
&andwaitcan exhaust CPU/RAM resources, and centralizing error logs becomes messy and complicated.
2. Docker Compose Build
Many teams leverage Compose because the configuration file is already present in their local development environment.
- Pros: Convenient without requiring additional configuration files. Recent Compose releases also support the
parallelflag. - Cons: Compose was fundamentally designed for container runtime orchestration (networking, volumes, restart policies). When advanced features are needed—such as multi-platform builds (combining amd64 and arm64), target inheritance, or pushing remote cache to AWS ECR/GitHub Registry—Compose quickly shows its limitations.
3. Docker Buildx Bake
Buildx Bake tackles packaging using a Directed Acyclic Graph (DAG) dependency model.
- Pros: The BuildKit engine automatically identifies independent parts to build in parallel, making full use of all CPU cores. Intuitive HCL syntax enables target grouping, common configuration inheritance, and pushing everything to registries with a single command.
- Cons: The team needs to invest time getting accustomed to Bake’s HCL or JSON syntax.
Real-World Impact of Adopting Bake
If a repository contains only a single service, standard docker build is sufficient. However, once a system reaches 3–4 or more services, Bake makes a tangible difference.
In a project consisting of 8 microservices (Golang backend, Next.js frontend, and multiple workers), GitHub Actions initially took over 16 minutes to run. After migrating entirely to docker-bake.hcl combined with the docker-container driver, the packaging time dropped to just 4 minutes and 30 seconds. This saved more than 60% in runner costs each month.
Step-by-Step Guide to Setting Up Docker Buildx Bake
Step 1: Set Up the Builder Instance
Docker Desktop already comes bundled with Buildx. However, the default builder typically uses the docker driver, which has several limitations. Create a new builder using the docker-container driver to unlock full parallelism and remote caching features:
# Check current buildx version
docker buildx version
# Create a new builder instance and set it as default
docker buildx create --name bake-builder --driver docker-container --use
# Boot and inspect the builder
docker buildx inspect --bootstrap
Step 2: Prepare the Directory Structure
Consider a standard project consisting of a Backend (Golang) and a Frontend (Node.js):
my-project/
├── backend/
│ └── Dockerfile
├── frontend/
│ └── Dockerfile
└── docker-bake.hcl
Step 3: Write the docker-bake.hcl Configuration File
Create a docker-bake.hcl file in the repository’s root directory:
# Define global variables with fallback values
variable "TAG" {
default = "latest"
}
variable "REGISTRY" {
default = "myregistry.local/app"
}
# Base target containing shared configurations
target "common" {
platforms = ["linux/amd64"]
args = {
BUILD_ENV = "production"
}
}
# Backend target inheriting all configurations from common
target "api" {
inherits = ["common"]
context = "./backend"
dockerfile = "Dockerfile"
tags = ["${REGISTRY}-api:${TAG}"]
}
# Frontend target inheriting from common
target "web" {
inherits = ["common"]
context = "./frontend"
dockerfile = "Dockerfile"
tags = ["${REGISTRY}-web:${TAG}"]
}
# Default group bundling both services
group "default" {
targets = ["api", "web"]
}
Step 4: Execute the Build with a Single Command
From the root directory, simply run:
docker buildx bake
BuildKit instantly analyzes the dependency graph. Base layers and source code for both services are pulled and compiled in parallel. The CLI renders dedicated progress bars for each target without swallowing logs.
Step 5: Flexibly Override Parameters
You can easily pass environment variables or target a specific service when debugging:
# Build only the API service with version v1.2.0
TAG=v1.2.0 docker buildx bake api
# Build and directly push images to the container registry
docker buildx bake --push
Step 6: Accelerate CI/CD with Remote Caching
The most valuable feature of Bake in CI/CD is its centralized remote caching. You just need to add the following to the common target:
target "common" {
platforms = ["linux/amd64"]
cache-from = ["type=registry,ref=${REGISTRY}-cache:common"]
cache-to = ["type=registry,ref=${REGISTRY}-cache:common,mode=max"]
}
With this setup, unchanged layers such as npm install or go mod download are retrieved directly from the registry. For subsequent commits, the runner only takes 20–30 seconds to complete the build process.
Conclusion
Docker Buildx Bake does far more than replace clunky shell scripts. It delivers standardization and incredible speed to your CI/CD pipelines. For microservices or monorepo projects, investing in a docker-bake.hcl configuration early on will save significant waiting time every single day.

