⚠️ Linux Prerequisites for Running Keploy Samples with Docker Compose

[Akshat005Chaudhary]

Keploy samples that use Docker Compose require Docker Compose v2 and a modern Buildx plugin. On Linux systems, older Docker tooling frequently co-exists and causes silent failures. Follow the requirements below to avoid setup issues.

✅ Mandatory Requirements (Linux)

1. Use Docker Compose v2 (not docker-compose v1)

Do NOT use:

docker-compose up

Always use:

docker compose up

Why:

• docker-compose (v1) is deprecated and end-of-life
• It uses an older Docker API and fails with modern Docker Engine versions
• Compose v2 is the officially supported implementation

Verify:

docker compose version
# version >= v5.0.0

To correctly install the latest Docker Engine Suite refer: Docker Documentation

2. Remove legacy docker-compose if present (important)

If both v1 and v2 exist, Linux will often invoke the wrong client.

sudo apt remove docker-compose
sudo rm -f /usr/bin/docker-compose
sudo rm -f /usr/local/bin/docker-compose

Confirm removal:

which docker-compose
# (should return nothing)

3. Ensure Docker Buildx ≥ 0.17 is installed

Docker Compose v2 delegates all builds to Buildx.
Older Buildx versions cause this error:

compose build requires buildx 0.17 or later

Install / upgrade Buildx:

sudo apt update
sudo apt install docker-buildx-plugin

Verify version:

docker buildx version
# (Version must be ≥ 0.17)

4. Remove old Buildx binaries if version does not update

If docker buildx version still shows an old version (e.g. 0.12.x), an older binary is shadowing the plugin.

Remove conflicting binaries:

rm -f ~/.docker/cli-plugins/docker-buildx
sudo rm -f /usr/local/lib/docker/cli-plugins/docker-buildx

Re-verify:

docker buildx version

5. Run the project

Once the above is satisfied:

docker compose up -d --build

ℹ️ Notes

• The version: field in docker-compose.yml is obsolete for Compose v2 and can be safely removed.
• These issues primarily affect Linux users. Docker Desktop (Windows/macOS) bundles compatible Compose and Buildx versions automatically.
• Mixing distribution-provided Docker packages with Docker’s official repository is the most common cause of these failures.

✅ Quick Preflight Check (Recommended)

Before running any Keploy Docker-based sample:

docker version
docker compose version
docker buildx version

All commands must succeed without errors.

[Achanandhi-M]

Hey @Akshat005Chaudhary

Thanks for the clarification!

Removing legacy docker-compose and upgrading Buildx resolve the issue.