Docker Compose depends_on — Fixing Container Startup Crashes

Every real-world application is more than one moving part. Your API needs a database. That database needs a volume so data survives restarts. Your frontend needs to know the API's address. Managing each with individual docker run commands is a copy-paste nightmare that breaks when a new developer joins or you move to a different machine.

Docker Compose is a declarative orchestrator for multi-container applications on a single host. You describe the desired state in YAML — services, networks, volumes, environment variables, health checks — and Compose handles creation, networking, and lifecycle ordering. The file is the documentation. The file is the deployment. There is no gap between what you describe and what runs.

The critical misconception: Compose is not just a convenience wrapper. It manages DNS resolution between services, network isolation between tiers, volume lifecycle across container restarts, and startup ordering with readiness gates. Understanding these mechanisms is what separates a working compose file from a production-grade one.

What Docker Compose Actually Does for Multi-Container Apps

Docker Compose is a declarative tool that defines and runs multi-container Docker applications from a single YAML file. Instead of manually wiring containers with docker run commands, you describe services, networks, and volumes in docker-compose.yml. The core mechanic: Compose translates that YAML into a set of Docker API calls, creating and linking containers in a user-defined order.

In practice, Compose handles three critical properties: service orchestration (which containers start, in what order), network isolation (each service gets its own DNS-resolvable hostname), and volume persistence (data survives container restarts). The depends_on directive controls startup sequencing, but it only waits for the container to start — not for the process inside to be ready. This is the source of most startup crashes.

Use Compose for local development, CI/CD integration tests, and single-host production deployments. It eliminates the need to manually manage container lifecycles, but it is not a production orchestrator — that's Kubernetes or Nomad. For teams running 3–10 services on one host, Compose provides the simplest path to reproducible environments.

The Anatomy of a docker-compose.yml File (and Why Every Key Matters)

A Compose file is a declaration of intent, not a script. You're telling Docker 'here is the world I want' — Compose figures out how to build it. That mental shift matters: you're not writing steps, you're describing a state.

Every Compose file has a few top-level keys. services is the main one — each entry is a container. volumes defines named storage that outlives containers. networks lets you control which services can see each other (by default Compose creates one shared network, which is great for getting started but dangerous if you want to isolate, say, your admin panel from your public API).

The depends_on key is widely misunderstood. It controls start order, not readiness. Your app container will start after the database container starts, but not after Postgres is actually ready to accept connections. That's a real gotcha we'll cover shortly. For readiness you need health checks.

The build key is your escape hatch from public images — point it at a directory with a Dockerfile and Compose builds the image itself before starting the container. This is how you develop locally with live code while still using Compose for orchestration.

Service configuration depth: Each service can specify image or build (mutually exclusive in intent — image pulls from a registry, build creates locally). The restart policy controls behavior on container exit: no (default), always, on-failure, unless-stopped. In production, unless-stopped is almost always correct — it restarts on crash but respects your manual docker compose stop.

Volume lifecycle: Named volumes declared under the top-level volumes: key are managed by Docker. They survive docker compose down but are destroyed by docker compose down -v. Bind mounts (host:path syntax) are managed by the host filesystem. Anonymous volumes (- /app/node_modules) are created by Docker and removed when the container is removed.

# docker-compose.yml — A full three-tier web application
# Services: React frontend, Node/Express API, PostgreSQL database

version: '3.9'

services:

  # ── PostgreSQL Database ──────────────────────────────────────────
  postgres_db:
    image: postgres:15-alpine          # Use the slim Alpine variant to keep image size small
    restart: unless-stopped            # Restart on crash, but respect manual `docker compose stop`
    environment:
      POSTGRES_USER: ${DB_USER}        # Pulled from .env file — never hardcode credentials
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    volumes:
      - postgres_data:/var/lib/postgresql/data   # Named volume: data persists across `down`/`up`
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql  # Seed script runs on first start
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER} -d ${DB_NAME}"]  # Actual readiness probe
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend_network   # Only the API can reach the DB — frontend cannot

  # ── Node.js / Express API ────────────────────────────────────────
  api_server:
    build:
      context: ./api          # Build from local Dockerfile in the /api directory
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - "3001:3001"           # Expose API to host for direct testing with Postman etc.
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres_db:5432/${DB_NAME}
      #                                                   ^^^^^^^^^^^
      #  'postgres_db' is the SERVICE NAME — Compose's built-in DNS resolves it automatically
      JWT_SECRET: ${JWT_SECRET}
    depends_on:
      postgres_db:
        condition: service_healthy   # Wait until the healthcheck PASSES, not just starts
    volumes:
      - ./api:/app             # Bind mount for hot-reload in development
      - /app/node_modules      # Anonymous volume: keep container's node_modules, don't overwrite with host
    networks:
      - backend_network
      - frontend_network

  # ── React Frontend (served via Nginx) ────────────────────────────
  web_frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - "80:80"               # Expose port 80 to the host machine
    environment:
      REACT_APP_API_URL: http://api_server:3001   # Container-to-container via service name
    depends_on:
      - api_server
    networks:
      - frontend_network      # Frontend can only see the API, never the raw database

# ── Named Volumes ────────────────────────────────────────────────────
volumes:
  postgres_data:              # Managed by Docker — survives `docker compose down`
                              # Destroyed only by `docker compose down -v`

# ── Networks ─────────────────────────────────────────────────────────
networks:
  backend_network:            # Isolated: only api_server and postgres_db
    driver: bridge
  frontend_network:           # Isolated: only web_frontend and api_server
    driver: bridge

Top-Level YAML Key Reference Table

The docker-compose.yml file has several top-level keys that control the entire multi-container stack. Each key serves a distinct purpose — volumes persist data, networks isolate traffic, and configs manage non-file configuration. Below is a reference table of every top-level key available in Compose specification version 3.9 (the most widely supported version across Docker Engine and Docker Desktop).

How they connect: The services block is the only required top-level key because it defines the actual containers. Every other key is optional and exists to support the services. For example, you reference a named volume like my_volume in a service's volumes: list only if you declared my_volume under the top-level volumes: key. If you don't declare it, Docker creates an anonymous volume instead.

The include key is a game-changer for multi-team projects. Instead of one monolithic file, each team owns their own Compose file, and the parent file includes them. This is how you compose microservices without a single 500-line file that no one understands. The included files' services, volumes, and networks are merged at runtime.

Docker Compose Command Cheat Sheet

Docker Compose commands follow a consistent pattern: docker compose <command> [options] [service...]. Below is a quick reference for the most frequently used commands in day-to-day development and debugging. These commands assume you are in the directory containing docker-compose.yml (or using the -f flag to point to one).

Command examples for real debugging: ```bash # Start the stack and rebuild the API image docker compose up --build -d

# Watch logs from the API service only docker compose logs -f api_server

# Shell into a running container to inspect environment docker compose exec -it api_server sh

# Run a one-off migration (remove container after) docker compose run --rm api_server npx prisma migrate deploy

# Check the entire resolved config (useful before prod deploy) docker compose config

# Stop everything and clean up named volumes (careful — destroys data) docker compose down -v ```

Pro tip: Use docker compose config --services to list all service names in the current project. This is invaluable when you have many services and need to reference them in scripts.

Environment Variables and Secrets — The Right Way vs. The Dangerous Way

Hardcoding passwords directly in docker-compose.yml is one of the most common and dangerous mistakes in real projects. If that file ever gets committed to a public repo — even accidentally — your credentials are exposed permanently (git history remembers everything).

The correct pattern is a .env file alongside your Compose file. Docker Compose automatically reads .env and substitutes ${VARIABLE_NAME} placeholders. You commit a .env.example with dummy values to your repo, and each developer (and your CI system) fills in the real .env locally. The actual .env lives in .gitignore.

For production, environment variables should come from your hosting platform's secret manager (AWS Secrets Manager, Doppler, HashiCorp Vault) injected at runtime — never baked into an image or a file on disk.

You can also use multiple Compose files with docker compose -f docker-compose.yml -f docker-compose.prod.yml up. The second file merges and overrides the first. This is how you maintain one base config and swap out dev-specific settings (like bind mounts and debug ports) for production-hardened ones without duplicating the whole file.

Secret exposure vectors: - Hardcoded in docker-compose.yml → committed to git → visible in git history forever - ENV in Dockerfile → baked into every image layer → visible in docker history and docker inspect - .env file not in .gitignore → committed to git → same as hardcoded - docker compose config output includes resolved secrets → if captured in CI logs, credentials are exposed

The right pattern for each environment: - Local development: .env file, in .gitignore, .env.example committed as template - CI/CD: secrets injected from CI platform secrets (GitHub Secrets, GitLab CI variables) - Production: secrets from a secrets manager (AWS Secrets Manager, Vault), mounted as files or injected as environment variables at deploy time

# .env.example — commit this to git as a template
# Copy to .env and fill in real values — NEVER commit .env itself

# Database credentials
DB_USER=your_db_username
DB_PASSWORD=your_secure_password_here
DB_NAME=your_app_db

# Auth
JWT_SECRET=replace_with_a_long_random_string_at_least_32_chars

# App config
NODE_ENV=development
API_PORT=3001

.env File vs environment Key — Two Separate Mechanisms, One Common Confusion

A recurring theme in every Docker Compose workshop: developers confuse the .env file with the environment key inside a service. They think the .env file sets environment variables inside the container. It does not. The .env file exists only for the Compose file parser — it provides values for variable interpolation (${VAR}) in the YAML. The environment key inside a service is what actually sets environment variables inside the container at runtime.

The separation of concerns is critical: - .env → feeds the YAML parser during docker compose config and docker compose up. - environment: (or env_file:) → feeds the container's OS environment.

If you define DB_PASSWORD in .env, the container does not automatically have a DB_PASSWORD environment variable. You must explicitly pass it via environment: or env_file: in the service definition. The .env file just makes ${DB_PASSWORD} resolve in the YAML — that resolved value can then be assigned to an environment: key, but you have to write the mapping.

Example of the confusion: ``yaml # docker-compose.yml services: api: image: my-api environment: - DATABASE_URL=postgres://user:pass@db:5432/mydb ` If the DATABASE_URL contains a password, that password is hardcoded in the YAML. The correct approach is to put the password in .env` and reference it:

In .env: `` DB_PASSWORD=supersecret ` In docker-compose.yml: `yaml services: api: image: my-api environment: - DATABASE_URL=postgres://user:${DB_PASSWORD}@db:5432/mydb ` Now the resolved DATABASE_URL inside the container will contain 'supersecret'. The .env file provided the value, but the environment` key set the variable.

When to use env_file: instead: If you have many environment variables, you can use the env_file: directive to point to a file that gets parsed line-by-line and sets each variable inside the container. This file can be different from the .env file. For example, env_file: ./app.env will read key=value pairs from that file and set them in the container. This is useful when you have a pre-existing env file from a non-Docker setup.

Priority order (highest wins): 1. environment: key with inline values (takes precedence). 2. env_file: pointed file (overrides .env indirectly via ${VAR}). 3. .env file variables (used for interpolation only, not directly passed). 4. Environment variables from the host shell when running docker compose up (if the variable is referenced with ${VAR} but not defined in .env). 5. Defaults from YAML anchors or extension fields.

Deceptively dangerous pattern: Never rely on .env to pass environment variables to the container without explicitly mapping them. If you forget to add the environment: key, your container won't see the variables, and your app might fail with an obscure error like DB_PASSWORD not set while you stare at a .env file that clearly has the value. The .env file is for Compose, not for the container.

# ── Example 1: environment key with hardcoded values (DO NOT DO THIS) ──
services:
  api:
    image: my-api
    environment:
      - DB_USER=admin
      - DB_PASSWORD=s3cret   # Hardcoded! Bad!

# ── Example 2: environment key using .env interpolation (CORRECT) ──
services:
  api:
    image: my-api
    environment:
      - DB_USER=${DB_USER}
      - DB_PASSWORD=${DB_PASSWORD}

# ── Example 3: env_file directive (alternative) ──
services:
  api:
    image: my-api
    env_file: ./api.env   # This file is read and each line becomes an env var

# ── Example 4: mixing .env interpolation with env_file ──
services:
  api:
    image: my-api
    env_file:
      - .env              # Can use .env as env_file (not recommended — confusing)
    environment:
      - SPECIAL_FLAG=true  # This overrides any same-named variable from env_file

Networking Between Containers — How Compose DNS Actually Works

This is where most intermediate developers have a fuzzy mental model, and it costs them hours of debugging. When Compose starts your services, it creates a virtual network and registers each service under its own DNS name — that name is simply the service name you defined in the YAML.

So when your API container wants to connect to Postgres, it doesn't use localhost (that points to itself) and it doesn't use an IP address (those change). It uses postgres_db:5432 — the service name and the container port, not the host-mapped port. This is a huge source of confusion: ports: '5432:5432' exposes port 5432 to your laptop. Other containers don't need that — they communicate on the internal network directly.

Multiple networks let you enforce security boundaries at the network layer, not just at the application layer. In our example, the frontend container literally cannot reach the database — there's no route. Even if someone finds an XSS vulnerability in your frontend, they can't pivot directly to the database because Compose's networking won't allow it.

Use docker compose exec api_server sh to shell into a running container and test DNS resolution live with nslookup postgres_db or curl http://api_server:3001/health from the frontend container.

DNS resolution internals: Compose uses Docker's embedded DNS server at 127.0.0.11. When a container resolves a service name, the request goes to this DNS server, which maps the service name to the container's internal IP on the appropriate network. If a container is on multiple networks, it can resolve services on all of them. If a container is on network A but not network B, it cannot resolve services that are only on network B.

Port mapping confusion: The ports directive maps HOST:CONTAINER. Your database connects at localhost:5432 from your laptop (host port). Your API connects at postgres_db:5432 from inside Docker (container port). These are completely separate network paths. Using the host port from inside a container (localhost:5432) either fails or connects to the wrong thing.

# ── Inspecting Compose Networks ──────────────────────────────────────

# List all networks Compose created for this project
docker network ls
# Output includes: app_backend_network, app_frontend_network

# Inspect who is on the backend network and their internal IPs
docker network inspect app_backend_network

# Shell into the running API container to test connectivity
docker compose exec api_server sh

# Inside the container — test that DNS resolves the DB service name
nslookup postgres_db
# Expected output:
# Server:    127.0.0.11      <-- Docker's embedded DNS resolver
# Address:   127.0.0.11:53
# Name:      postgres_db
# Address:   172.20.0.2      <-- Internal IP (changes every run, that's why we use names)

# Test that the DB is reachable on its CONTAINER port (not the host-mapped one)
curl -v telnet://postgres_db:5432
# This should open a TCP connection — if it fails, check your 'networks' config

# Verify the frontend CANNOT reach postgres directly (network isolation working)
docker compose exec web_frontend sh
nslookup postgres_db
# Expected: nslookup: can't resolve 'postgres_db'
# This is CORRECT — it proves your network isolation is working

Profiles and Overrides — Running Different Stacks for Dev, Test and CI

A subtle but powerful Compose feature is profiles. You might have services that should only run in certain contexts — a database admin UI like pgAdmin in development, a mock email server in testing, or a metrics exporter in production. Profiles let you tag services and opt into them at runtime.

With docker compose --profile dev up, only services tagged with the dev profile (plus services with no profile) start. Your CI pipeline can run docker compose --profile test up --abort-on-container-exit to spin up integration test dependencies, run tests, and tear down — without launching the full dev UI tooling.

Compose file overrides are the production deployment pattern. You maintain a docker-compose.yml as the base truth and a docker-compose.prod.yml that overrides just the production-specific bits: replaces bind mounts with proper volumes, removes debug ports, adds resource limits, and switches to pre-built images instead of local builds. This avoids the 'it works on my machine' trap without duplicating hundreds of lines of YAML.

Override merge behavior: When multiple files are specified with -f, Compose deep-merges them. Arrays (like ports, volumes, environment) are replaced, not appended — if the override file specifies volumes: [], the base file's volumes are completely replaced. Scalar values (like image, restart) are overwritten. This is why docker compose config is essential — it shows the final merged result before you deploy.

Profile use cases beyond dev/prod: - Testing: profile test for mock services (WireMock, LocalStack) - Monitoring: profile monitoring for Prometheus, Grafana, cAdvisor - Debugging: profile debug for a debugger sidecar or log aggregator - Migration: profile migration for a one-shot database migration container

# docker-compose.prod.yml — Production overrides
# Usage: docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
#
# This file MERGES with docker-compose.yml — only specify what changes.

version: '3.9'

services:

  api_server:
    # In prod, use a pre-built image from your registry instead of local build
    image: ghcr.io/your-org/api-server:${APP_VERSION:-latest}
    build: !reset null    # Remove the build config from the base file
    volumes: []           # Remove the dev bind mount — no hot reload in prod
    environment:
      NODE_ENV: production
    deploy:
      resources:
        limits:
          cpus: '0.50'      # Cap CPU usage per container instance
          memory: 512M      # Cap memory — prevents runaway leaks taking down the host
        reservations:
          memory: 256M
    logging:
      driver: "json-file"   # Structured logs for log aggregators
      options:
        max-size: "10m"     # Rotate logs — don't fill the disk
        max-file: "5"

  web_frontend:
    image: ghcr.io/your-org/web-frontend:${APP_VERSION:-latest}
    build: !reset null
    volumes: []

  # pgAdmin only runs in dev — it's tagged with 'dev' profile
  pgadmin:
    image: dpage/pgadmin4:latest
    profiles:
      - dev               # Only starts when: docker compose --profile dev up
    ports:
      - "5050:80"
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@local.dev
      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD:-localdevonly}
    networks:
      - backend_network

Volumes That Survive the Wreck — Persistent Data You Can Actually Trust

Every junior dev learns the hard way: docker compose down is a liar. It doesn't kill your data unless you tack on -v. But here's the real problem — most teams treat volumes like magic bags that hold stuff. They're not. They're mounts with specific behaviors, and if you don't understand binding vs named volumes vs tmpfs, your database will vanish when your CI runner resets. Why it matters: containers are cattle, but your Postgres data is a pet. Named volumes outlive containers, survive restarts, and can be shared across services without permission nightmares. Bind mounts are for development — they mirror your host filesystem, but they break in production when your orchestration layer doesn't have the same paths. tmpfs is for secrets you want to incinerate on container stop. The how: define volumes under the top-level volumes: key, then mount them with source and target in each service. Always use driver: local unless you're connecting to NFS or cloud block storage. Never mount a macOS or Windows host path into a Linux container expecting consistent filesystem behavior — you'll get permission issues and symlink garbage. Test your persistence model with a forced kill, not a graceful stop.

// io.thecodeforge — devops tutorial

version: "3.8"

services:
  postgres:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: orders   # database name the app expects
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}   # never hardcode
    volumes:
      - postgres_data:/var/lib/postgresql/data   # named volume survives down/up
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d orders"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:
    driver: local   # default, but explicit is better than implicit

Custom Networks Stop the Noise — Why Port Conflicts Are a Self-Inflicted Wound

Default bridge networks work fine until two apps both claim port 8080. Then you learn: Compose creates a dedicated network per project, but by default every service can talk to everything else. That's fine for a three-service app. It's a disaster when you're running a dozen microservices and one misconfigured container starts DNS-recycling requests into the wrong database. The fix: separate your traffic into logical networks. You don't need a single flat plane. Split internal API communication from public-facing ingress traffic, and isolate data-plane traffic from admin or monitoring channels. Why this works: Compose's internal DNS resolves container names to IPs, but on a shared network, any container can reach any other service. By creating an internal or frontend network and attaching only the relevant services, you enforce zero-trust boundaries at the network level — no firewall rules needed. The how: define networks under the top-level networks: key, then assign each service to specific networks with networks: [...]. Use driver: bridge for single-host setups; use attachable: false to prevent stray containers from joining. For extra paranoia, mark the internal network as internal: true — no outbound internet access. Test with docker compose exec <service> ping <other-service> to verify isolation.

// io.thecodeforge — devops tutorial

version: "3.8"

services:
  api-gateway:
    image: nginx:alpine
    ports:
      - "443:443"   # only gateway touches the outside world
    networks:
      - frontend   # public-facing
      - backend    # can talk to services, but services can't reply publicly

  orders-service:
    image: orders:latest
    expose:
      - "3000"   # no host port — only reachable via Compose DNS
    networks:
      - backend
      - db-network   # isolated from frontend traffic

  postgres:
    image: postgres:15-alpine
    networks:
      - db-network   # database is invisible to api-gateway entirely

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: false   # still allowed to reach internet for updates
  db-network:
    driver: bridge
    internal: true    # no internet — database doesn't need it

Healthchecks That Actually Fail — Stop Waiting for Containers That Aren't Ready

You've seen the pattern: a Dockerfile with CMD to start the app, and Compose with depends_on. Then your Rails app starts before Postgres finishes initializing, throws a connection error, and crashes. depends_on only waits for the container to start — not for the process inside to be healthy. That's the gap. Why it matters: in production, your orchestrator won't route traffic to a container that hasn't passed its healthcheck. If you don't define one, you're relying on timing luck. And timing luck fails under load, on cold starts, and when your database image upgrades to a new major version with a slower init sequence. The fix: add a healthcheck block to every service that depends on another. Use start_period to give slow services time to initialize before the health checker starts hammering them. Use retries and interval that match your SLAs. The how: define healthcheck at the service level with a test command that returns exit code 0 for healthy, 1 for unhealthy. For HTTP services, use curl -f http://localhost/health. For databases, use the built-in client tool (e.g., pg_isready, mongosh --eval). Then use depends_on with condition: service_healthy — this makes Compose wait until the dependency passes its check before starting the dependent service. Without condition, depends_on is just a startup order hint, not a guarantee.

// io.thecodeforge — devops tutorial

version: "3.8"

services:
  postgres:
    image: postgres:15-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d orders"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 30s   # gives Postgres time to init before grace period

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 10s

  app:
    image: my-app:latest
    depends_on:
      postgres:
        condition: service_healthy   # won't start until pg_isready passes
      redis:
        condition: service_healthy
    ports:
      - "3000:3000"

Install Docker Compose on Ubuntu — Two Paths, One Reliable Outcome

Docker Compose is not installed by default on Ubuntu. The apt package lags behind upstream releases, so you must install manually to get current features. The recommended method downloads the binary directly from the GitHub releases page. First, check your kernel version with uname -s and architecture with uname -m. Then fetch the binary for your platform using curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose. Apply executable permissions with chmod +x /usr/local/bin/docker-compose. Verify the installation with docker-compose --version. This binary approach avoids stale package versions and gives you access to Compose V2 features like docker compose (without the hyphen) commands. Always pin to a specific version in CI/CD pipelines to prevent unexpected breaking changes.

// io.thecodeforge — devops tutorial

// Step 1: Download the Compose binary
curl -SL \
  https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 \
  -o /usr/local/bin/docker-compose

// Step 2: Apply executable permissions
chmod +x /usr/local/bin/docker-compose

// Step 3: Verify version
// Expected output: Docker Compose version v2.32.4
docker-compose --version

Step 2: Download the Software — Where Most Install Guides Go Wrong

Downloading Docker Compose looks trivial but hides a critical failure point: architecture mismatch. Many copy-paste commands assume x86_64, but if your Ubuntu machine runs on ARM (like a Raspberry Pi or AWS Graviton), the binary will fail silently. Always detect the architecture dynamically using uname -m and substitute it into the download URL. For ARM systems, replace x86_64 with aarch64. The full URL pattern is https://github.com/docker/compose/releases/latest/download/docker-compose-linux-{arch}. After download, verify the SHA256 checksum against the official release page — a corrupted download will produce obscure "Exec format error" messages. This step prevents wasting hours debugging container orchestration when the real problem is a mismatched binary architecture. Store the downloaded binary in /usr/local/bin to ensure it's in the system PATH without modifying environment variables.

// io.thecodeforge — devops tutorial

// Step 2: Dynamic architecture detection
ARCH=$(uname -m | sed 's/x86_64/x86_64/;s/aarch64/aarch64/')

// Download with correct architecture
curl -SL \
  "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-${ARCH}.tar.gz" \
  -o /tmp/docker-compose.tar.gz

// Extract the binary
tar -xzf /tmp/docker-compose.tar.gz -C /usr/local/bin/

// Clean up
rm /tmp/docker-compose.tar.gz