{"id":4726,"date":"2026-02-28T21:01:57","date_gmt":"2026-02-28T15:31:57","guid":{"rendered":"https:\/\/itsupportwale.com\/blog\/master-docker-compose-the-ultimate-guide-for-developers\/"},"modified":"2026-02-28T21:01:57","modified_gmt":"2026-02-28T15:31:57","slug":"master-docker-compose-the-ultimate-guide-for-developers","status":"publish","type":"post","link":"https:\/\/itsupportwale.com\/blog\/master-docker-compose-the-ultimate-guide-for-developers\/","title":{"rendered":"Master Docker Compose: The Ultimate Guide for Developers"},"content":{"rendered":"

text
\n[2024-05-22T03:14:02.881Z] ERROR: Container “api-gateway” exited with code 137 (OOMKilled)
\n[2024-05-22T03:14:05.112Z] CRITICAL: Service “auth-provider” failed to bind to 0.0.0.0:8080. Address already in use.
\n[2024-05-22T03:14:05.115Z] FATAL: Dependency check failed. “postgres-db” not reachable at 172.17.0.2:5432.
\n[2024-05-22T03:14:05.118Z] STACK_TRACE: deploy.sh: line 44: docker run -d –name api-gateway …
\n[2024-05-22T03:14:05.120Z] SYSTEM_STATE: Load Average 45.12, 38.01, 22.10. Disk I\/O 98% saturated.
\n[2024-05-22T03:14:05.122Z] TERMINATING: Manual cleanup required. God is dead and we killed Him with a shell script.<\/p>\n

# The YAML That Bit Back: A Post-Mortem on Orchestration Laziness\n\nI\u2019ve been awake for 48 hours. My blood is 60% espresso and 40% spite. While the rest of the engineering team was dreaming of "clean code" and "agile velocity," I was watching our production environment melt into a puddle of unrouted packets and orphaned processes. The culprit? A "clever" bash script named `deploy.sh`, written by a junior developer who thought `docker compose` was "too much overhead for a simple microservice stack."\n\nWe are running Docker Engine v25.0.3. We have the tools. We have the specs. And yet, I spent my Sunday morning manually killing zombie containers because someone decided that a sequence of `docker run` commands was a viable orchestration strategy. It isn\u2019t. It\u2019s a suicide note written in Bourne Shell.\n\n## 1. The Bash Script Death Spiral\n\nThe incident began when the `deploy.sh` script attempted to update the `api-gateway`. In a sane world\u2014a world governed by `docker compose`\u2014this would be an atomic operation. Instead, the script executed a `docker stop api-gateway` followed by a `docker rm api-gateway`. Between those two commands, the health check for our load balancer failed, the auto-scaler panicked, and the script continued blindly to the next line.\n\nManual `docker run` commands are a professional liability because they lack state awareness. When you execute `docker run`, you are throwing a binary at the kernel and hoping it sticks. There is no source of truth. There is no desired state. There is only the immediate, fleeting command.\n\nThe junior\u2019s script didn't account for the fact that the `auth-provider` container had crashed five minutes earlier. Because there was no orchestration layer to verify the health of dependencies, the `api-gateway` started, tried to connect to a non-existent auth service, and entered a crash loop. But the script didn't care. It just kept running `docker run` for the next ten services, each one failing more spectacularly than the last.\n\nBy the time I was paged at 3:15 AM, the host was a graveyard of containers in `Exited (1)` states, all of them holding onto port bindings that prevented the script from being re-run. This is the "Death Spiral." Without the declarative nature of `docker compose`, you aren't managing a system; you're playing a high-stakes game of Whac-A-Mole where the hammer is broken and the moles are on fire.\n\n## 2. The Race Condition of the Unchecked Container\n\nThe second stage of the failure was the database. In the junior's "orchestration" script, the PostgreSQL container was started first, followed immediately by the application. \n\n```bash\n# The "Clever" Way (i.e., The Wrong Way)\ndocker run -d --name postgres-db postgres:16\ndocker run -d --name app-service my-app:latest\n<\/code><\/pre>\n
The problem? PostgreSQL takes approximately 10 to 15 seconds to initialize its internal storage and start listening on port 5432. The application container, written in a language that prizes “startup performance,” tried to connect in 0.5 seconds. It failed. It died. It didn’t have a retry loop because “the infrastructure should handle it.”<\/p>\n
This is where we exploit the depends_on<\/code> feature of the Compose specification v2.24.6. We don’t just want the container to be running<\/em>; we want it to be ready<\/em>.<\/p>\n
services:\n  postgres-db:\n    image: postgres:16\n    healthcheck:\n      test: ["CMD-SHELL", "pg_isready -U postgres"]\n      interval: 5s\n      timeout: 5s\n      retries: 5\n    networks:\n      - backend_mesh\n\n  app-service:\n    image: my-app:latest\n    depends_on:\n      postgres-db:\n        condition: service_healthy\n    networks:\n      - backend_mesh\n    deploy:\n      resources:\n        limits:\n          cpus: '0.50'\n          memory: 512M\n<\/code><\/pre>\n
In this snippet, docker compose<\/code> acts as the adult in the room. It understands the dependency graph. It waits for the pg_isready<\/code> command to return a zero exit code before it even attempts to pull the app-service<\/code> image. This prevents the 3 AM “Database not found” errors that haunt my nightmares. The junior dev’s bash script has no concept of a healthcheck<\/code>. It only knows if the docker run<\/code> command itself succeeded, which it always does, because the daemon successfully started<\/em> the container, even if the process inside is currently vomiting stack traces.<\/p>\n
\n
Table of Contents<\/p>\n