Technical Analysis: Resolving docker-compose Command Missing Issues in GitLab CI

Problem Background and Diagnosis

When integrating Docker containerized builds into GitLab CI/CD pipelines, developers frequently encounter the docker-compose: not found error. The root cause of this issue lies in misunderstanding the composition of official Docker images. When using image: docker:latest as the CI runtime environment, you're actually using a lightweight Docker client image based on Alpine Linux.

Technical Root Cause Analysis

Alpine Linux is renowned for its minimal size, but this means many standard tools are excluded by default. By executing docker run --rm -it docker sh to enter the container environment, then running find / -iname "python", you'll discover that the Python interpreter is completely absent from this image. Since docker-compose has traditionally been distributed as a Python package, the lack of a Python environment naturally prevents docker-compose from running.

This design choice reflects the philosophy of Docker official images: keeping core images minimal, allowing users to add additional components based on specific needs. For scenarios requiring complete development environments, users need to build their own images or select more comprehensive alternatives.

Solution Comparison

Solution 1: Using Official docker/compose Image

Docker officially provides the dedicated docker/compose image, which is the most straightforward solution. This image comes pre-installed with docker-compose tools and can be directly used in GitLab CI:

image:
  name: docker/compose:latest
  entrypoint: ["/bin/sh", "-c"]

services:
  - docker:dind

variables:
  DOCKER_HOST: tcp://docker:2375/
  DOCKER_DRIVER: overlay2

It's important to note that for older versions of docker-compose (prior to 1.25), you must override the entrypoint to ["/bin/sh", "-c"], otherwise command execution will fail due to entrypoint script issues.

Solution 2: Dynamic Installation of docker-compose

Another approach is to dynamically install docker-compose during CI pipeline execution:

image: docker
services:
  - docker:dind

build:
  script:
    - apk add --no-cache docker-compose
    - docker-compose up -d

While this method is simple, it requires reinstalling docker-compose every time the pipeline runs, increasing build time. Additionally, container management can become complex in docker-in-docker environments, requiring additional cleanup mechanisms to prevent old containers from continuing to run.

Solution 3: Creating Custom Images

For long-term projects, creating custom Docker images is the most sustainable solution. You can build customized images containing docker-compose based on the docker:latest image:

FROM docker:latest
RUN apk add --no-cache docker-compose

After pushing the built image to a container registry, reference it in GitLab CI:

image: your-registry/custom-docker-compose:latest

This approach provides optimal performance and reproducibility but requires maintaining additional image build pipelines.

Modern Best Practice: Migrating to docker compose V2

The most significant technical evolution currently is migrating from the standalone docker-compose tool (Compose V1) to the docker compose command integrated into Docker CLI (Compose V2). Since Docker Desktop 3.4.0, docker compose has become part of the standard Docker installation.

For GitLab CI configurations using the docker:latest image, you can now directly use:

image: docker:latest

services:
  - docker:dind

before_script:
  - docker info
  - docker compose version

buildJob:
  stage: build
  script:
    - docker compose build

This migration not only solves tool availability issues but also provides better performance, tighter Docker integration, and long-term technical support guarantees.

Security and Configuration Considerations

When using docker-in-docker (DinD) in GitLab CI, security configurations must be considered:

1. Privileged Mode: GitLab Runner needs to run in privileged mode or have appropriate Linux capabilities configured
2. TLS Configuration: By default, DinD uses TLS-encrypted communication. In CI environments, TLS can be disabled to simplify configuration, but this reduces security
3. Storage Driver: The overlay2 storage driver is recommended for optimal performance
4. Resource Limits: Reasonably configure memory and CPU limits to prevent CI jobs from consuming excessive resources

Conclusion and Recommendations

The key to solving docker-compose missing issues in GitLab CI lies in understanding the compositional differences between various images. For new projects, it's strongly recommended to directly use docker compose V2, avoiding dependency on standalone docker-compose tools. For existing projects, choose appropriate solutions based on specific needs: short-term projects can use dynamic installation, while long-term projects should build custom images or migrate to modern toolchains.

Regardless of the chosen solution, ensure the repeatability, security, and performance of CI/CD pipelines. Regularly reviewing and updating Docker-related configurations, keeping up with the latest developments in containerization technology, is key to maintaining development efficiency.