Docker Compose Evolution: From V1 to V2 & Enterprise Architecture

1. The Architectural Shift: Why V1 Was Deprecated

For nearly a decade, Docker Compose V1 was the de facto standard tool for defining and orchestrating multi-container local environments. However, V1 was implemented as a standalone, interpreted Python application (invoked via the hyphenated binary docker-compose). This design introduced notable operational friction into modern container pipelines:

• Separate Python Runtime Overhead: Required standalone installation packages, pip dependencies, or pre-compiled binaries that often had dependency version conflicts with host systems.
• Inconsistent CLI UX: The flags, authentication contexts, and daemon connection logic diverged between the primary docker CLI and the docker-compose binary.
• Lack of Modern Engine Integration: Lacked native integration with modern Docker Engine subsystems like BuildKit, Buildx, and multi-platform compilation contexts.

To solve this, Docker introduced Docker Compose V2. Completely rewritten in Go (Golang), Compose V2 is integrated directly into the Docker CLI as a native plugin (invoked as docker compose with a space). It matches the execution speed of the host daemon, shares Docker configuration files directly, and adheres to the open Compose Specification.

2. Structural Differences: Compose V1 vs. Compose V2

Migrating enterprise projects to Compose V2 requires understanding several critical architectural shifts:

3. Enterprise Compose Specification Blueprint (compose.yaml)

The following production-ready specification demonstrates modern Compose standards: explicit project naming, health-check conditions, selective execution profiles, persistent storage volumes, and isolated custom bridge networks:

name: enterprise-cloud-stack

services:
  # Application API Gateway Service
  api-gateway:
    build:
      context: ./backend
      dockerfile: Dockerfile
    image: cicdclouds/api-service:2.4.0
    container_name: production-api-gateway
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - APP_ENV=production
      - DB_HOST=postgres-db
      - DB_PORT=5432
      - DB_NAME=appdb
      - DB_USER=dbadmin
      - DB_PASSWORD_FILE=/run/secrets/db_password
    depends_on:
      postgres-db:
        condition: service_healthy
    networks:
      - backend-tier
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  # Database Engine with Health Checks
  postgres-db:
    image: postgres:16-alpine
    container_name: production-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: dbadmin
      POSTGRES_PASSWORD: SecretProductionPassword123!
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dbadmin -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s
    networks:
      - backend-tier

  # Debug & Monitoring Service (Selective Profile)
  database-admin:
    image: dpage/pgadmin4:latest
    container_name: staging-pgadmin
    profiles:
      - debug
    ports:
      - "5050:80"
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@cicdclouds.com
      PGADMIN_DEFAULT_PASSWORD: PgAdminSecurePassword456!
    depends_on:
      postgres-db:
        condition: service_healthy
    networks:
      - backend-tier

volumes:
  postgres-data:
    driver: local

networks:
  backend-tier:
    driver: bridge

4. Key Operational Enhancements in Compose V2

1. Elimination of the version: Attribute

In V1, developers had to continually bump the schema version (from 2.x to 3.8) to use new features. In Compose V2, the specification is unified into a living document. The top-level version: string is officially ignored; Docker automatically evaluates all supported top-level properties.

2. True Application Health Synchronization

In Compose V1, depends_on merely waited for the target container to start—not for the database or process inside it to be ready to accept TCP sockets. In Compose V2, condition: service_healthy delays dependent containers until the target's healthcheck probes return exit code 0.

3. Selective Workload Execution via profiles

Compose profiles allow developers to define services that do not start by default. In the example above, database-admin only spins up when explicitly requested:

# Start only primary production services
docker compose up -d

# Start production services + debug profile tools
docker compose --profile debug up -d

5. Production Pitfalls & Troubleshooting Guide

When managing multi-container stacks in CI/CD and production environments, watch out for these frequent issues:

1. The DNS Hostname Break (Underscores vs. Hyphens)

In Compose V1, containers were named using underscores (e.g., stack_api_1). Compose V2 switched to hyphens (stack-api-1). If any downstream scripts, log aggregators, or custom reverse proxies hardcoded container hostnames with underscores, connections will immediately fail with NXDOMAIN errors. Always use the abstract service name (e.g., postgres-db) as the network hostname instead of individual container instance names.

2. Orphaned Containers Lingering in the Background

When you remove or rename a service in your compose.yaml file, issuing docker compose up -d will not delete the retired container by default. It remains running as an "orphan", continuing to consume RAM and port bindings. Always include the clean-up flag during deployments:

docker compose up -d --remove-orphans

3. Race Conditions During Stack Termination

Using docker compose down immediately terminates containers. If your databases are executing writes, abrupt shutdowns can corrupt files. Use graceful timeouts or issue stop signals before teardown:

# Allow running services 30 seconds to drain active database connections
docker compose down --timeout 30