Add fallback registry support and alternative image mapping in docker-compose #13733

Description

This feature request proposes adding native support in docker-compose for defining multiple container registries (primary and fallback) and enabling automatic failover when the primary registry is unavailable. It also introduces optional alternative image mappings per registry.

Problem

Currently, docker-compose only supports a single image reference per service:

services:
  app:
    image: myorg/myapp:1.0

If the primary registry (e.g. Docker Hub) becomes unavailable due to outage, rate limiting, or network issues, deployments fail immediately.

There is no built-in mechanism for:

• Automatic fallback to another registry (e.g. GHCR, ECR)
• Defining alternative image locations
• Transparent retry logic for image pulls

This forces users to rely on external scripts or CI/CD logic, increasing complexity and reducing reliability.

Proposed Solution

1. Global registry fallback configuration

x-registries:
  primary: docker.io
  fallback: ghcr.io

2. Service-level fallback image definition

services:
  app:
    image:
      primary: myorg/myapp:1.0
      fallback: ghcr.io/myorg/myapp:1.0

3. Automatic fallback behavior

When pulling images:

1. Attempt to pull from primary registry
2. If it fails (network error, timeout, 5xx errors):
   • Automatically retry using fallback image

Example:

docker pull myorg/myapp:1.0
→ fails

docker pull ghcr.io/myorg/myapp:1.0
→ succeeds

4. Optional registry mapping per service

services:
  app:
    image: myorg/myapp:1.0
    registry_fallback:
      docker.io: myorg/myapp:1.0
      ghcr.io: ghcr.io/myorg/myapp:1.0

Expected Behavior

• Primary registry is always attempted first
• Fallback registry is automatically used on failure
• No manual intervention required
• Works transparently with docker compose up

Benefits

• Improved deployment reliability
• Resilience against registry outages (e.g. Docker Hub downtime)
• Simplified multi-registry strategies
• Better CI/CD and production robustness
• Reduced need for custom scripting

Use Cases

• Production systems requiring high availability
• CI/CD pipelines using multiple registries
• Organizations mirroring images across Docker Hub and GHCR
• Edge environments with unstable connectivity
• Disaster recovery scenarios

Alternatives Considered

• CI/CD-based image rewriting
• Manual multi-registry tagging and pushing
• Kubernetes-based imagePullPolicy strategies

These approaches are either external, complex, or not integrated into docker-compose workflows.

Summary

This feature would enhance docker-compose by adding native registry failover support, improving resilience and simplifying multi-registry deployments while preserving declarative configuration.