Docker Compose Evolution: Major Changes Since Oct 2023

November 20, 2024

Docker Compose Evolution: Major Changes Since October 2023

Since October 2023, Docker Compose has undergone significant evolution with important structural changes, new features, and improvements in developer experience. This comprehensive guide covers the major updates and changes that developers should be aware of.

Breaking Changes and Deprecations

Version Field Deprecation

The version field in docker-compose.yaml is now completely deprecated. Modern Docker Compose files should no longer include version specifications:

# OLD (Deprecated)
version: "3.8"
services:
  web:
    image: nginx

# NEW (Recommended)
services:
  web:
    image: nginx

Docker Compose Command Changes

The standalone docker-compose (with hyphen) command is now considered legacy and is in maintenance mode:

# OLD (Deprecated)
docker-compose up -d

# NEW (Recommended)
docker compose up -d

Key Points:

docker compose is now integrated directly into the Docker CLI.
The Python-based docker-compose tool is only receiving maintenance updates.
New features are exclusively added to docker compose.
Modern Docker Desktop installations default to docker compose.

Additional Deprecations

Several legacy fields are now discouraged:

links: Use Docker networks instead.
container_name: Allow Docker to manage container names dynamically.
Legacy volume mount syntax: Use the new long-form syntax.
Direct use of host ports without ranges: Use port ranges when possible.

Major YAML Structure Updates

Enhanced Service Definitions

#file: noinspection ComposeMissingKeys
services:
  myapp:
    build:
      args:
        - buildno=1
      ssh:
        - default=/path/to/key
      network: host
      platforms:
        - "linux/amd64"
        - "linux/arm64"

    healthcheck:
      start_period: 30s
      interval: 10s
      retries: 3
      start_interval: 5s

Improved Dependencies and Conditions

services:
  web:
    depends_on:
      db:
        condition: "service_healthy"
        restart: true
        required: false

Modern Volume Mount Syntax

services:
  app:
    volumes:
      - type: bind
        source: ./app
        target: /app
        bind:
          create_host_path: true
      - type: volume
        source: data
        target: /data
        volume:
          nocopy: true

New Features and CLI Enhancements

New Commands

docker compose attach: Attach to service containers for debugging.
docker compose stats: Live resource usage monitoring.
docker compose watch: Automatic service updates during development.
docker compose logs --index: Select logs from specific replicas.
docker compose exec --privileged: Run commands inside a container with elevated privileges.
docker compose cp: Copy files between the host and a service's container.

Enhanced Build and Deploy Options

# Build with dependencies
docker compose build --with-dependencies

# Convert compose files
docker compose convert --no-path-resolution

# Enhanced profile management
docker compose --profile prod --profile dev up
docker compose --profile-inherit=false up

# Improved service operations
docker compose up --wait
docker compose up --quiet-pull
docker compose down --remove-orphans

Docker Compose Watch

File Watch Configuration

The new x-develop section in the Docker Compose file allows for more sophisticated control over file watching and service updates:

services:
  web:
    build: .
    x-develop:
      watch:
        - path: ./src
          action: sync
          target: /app/src
        - path: ./package.json
          action: rebuild

Watch Features

Automatic service updates during development.
Configurable watch paths and actions (e.g., sync, rebuild).
Synchronized file updates without rebuilds.
Selective rebuild triggers.
Support for multiple watch configurations per service.

Security and Resource Management

Security Improvements

services:
  web:
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - NET_ADMIN

Security Updates

Critical patches for remote code execution (RCE) vulnerabilities in Docker extensions.
Enhanced validation of extension descriptions and publisher URLs.
Improved container isolation defaults.
Regular security maintenance releases.

Resource Management

Introduction of Resource Saver mode in Docker Desktop to reduce memory footprint when idle.
Improved handling of container lifecycle.
Better network conflict detection.
Enhanced build cache management with layer optimization.
More efficient handling of build cache layers.
Optimized cache invalidation strategies.

Docker Desktop Integration

Compose Watch GA Release

Docker Desktop 4.24 introduced the Compose Watch GA release.
Allows developers to automatically update and preview running services as they edit code without manually triggering builds.
Significantly enhances the "inner loop" of development by reducing manual steps.

Resource Optimization

Resource Saver mode for reduced memory footprint.
Better handling of idle resources.
Improved performance during development.
Optimized build cache handling.

Migration Tips

Remove the version field from all compose files.
Update CI/CD pipelines to use docker compose instead of docker-compose.
Review and update documentation and scripts accordingly.
Verify the Go-based implementation with docker compose version.
Test services with new dependency handling.
Review security configurations.
Replace deprecated fields with modern alternatives.
Update file watch configurations to use x-develop.

Best Practices

Use Docker networks instead of legacy linking (links).
Implement proper healthchecks for service dependencies.
Utilize build cache optimization features.
Configure appropriate resource limits.
Implement proper security measures.
Use modern volume mount syntax.
Leverage file watch for development efficiency.

Looking Forward

Docker Compose follows a rolling release model, and new features are continuously being added. Stay updated with the latest advancements by regularly consulting the official Docker documentation and release notes.