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

[hbenali]

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.