---
title: Infra — Risques & vigilance : Docker
domain: infra
bucket: risques
tags: [docker, dns, hostname, compose, tailscale, networking]
applies_to: [implementation, review, debug, architecture]
severity: high
validated_on: 2026-06-25
source_projects: [apps/stirling-pdf, infra/postgres]
---

# Infra — Risques & vigilance : Docker

> Extrait de la base de connaissance Lead_tech. Voir `knowledge/infra/risques/README.md` pour l'index complet.

---

<a id="risque-docker-collision-dns-hostname-service"></a>
## Collision DNS Docker : hostname container vs service name

### Risques

- Dans un `docker-compose.yml`, déclarer `hostname: <X>` sur un service alors qu'un autre service du même compose s'appelle `<X>` crée **deux entrées A** pour le nom `<X>` dans le DNS embarqué Docker (`127.0.0.11`) :
  1. le service name `<X>` (résolu vers l'IP du container du service),
  2. le `hostname: <X>` du container voisin.
- Un autre container du même network qui fait `getent hosts <X>` peut tomber sur **l'une ou l'autre selon l'ordre d'enregistrement** — non déterministe entre `docker compose up` successifs (dépend de l'ordre de démarrage).

### Symptômes

- Un service en réseau interne retourne 200 sur son IP directe mais `connection refused` quand on le hit par son service name depuis un voisin.
- **Aucune erreur explicite** dans les logs : juste un `connection refused` qui ressemble à "l'app n'écoute pas".
- Cas typique sidecar Tailscale : `tailscale serve` proxie vers `app:8080` mais le DNS résout `app` vers le sidecar lui-même → 502 côté HTTPS.

### Bonnes pratiques / mitigations

```yaml
# ❌ collision DNS — "app" peut résoudre vers le sidecar
services:
  app:
    image: monapp        # service name DNS = "app"
  proxy:
    image: nginx
    hostname: app        # ⚠ collision

# ✅ pas de hostname Docker : le service name reste la seule entrée DNS
services:
  app:
    image: monapp
  proxy:
    image: nginx
    # hostname Docker non défini → ID container random
    # les voisins s'adressent au proxy via le service name "proxy"
```

- **Règle** : ne jamais mettre `hostname: <X>` quand un service du même compose s'appelle `<X>`.
- **Cas sidecar Tailscale** : ne pas mettre `hostname: <app>` pour matcher `TS_HOSTNAME`. `TS_HOSTNAME` est lu par tailscaled et fixe le nom **côté tailnet**, totalement décorrélé du DNS Docker interne. Laisser le hostname Docker par défaut (voir `knowledge/infra/patterns/tailscale.md`).

### Diagnostic

```bash
# Dans le container qui fait l'appel
docker exec <caller> getent hosts <name-resolved>
# Plus d'une ligne pour le même nom → collision DNS Docker
```

- Contexte technique : Docker DNS / Compose / sidecar Tailscale — apps/stirling-pdf 27-05-2026

---

<a id="risque-docker-reseau-partage-stacks"></a>
## Réseau Docker partagé entre stacks — voir post-mortem

Un réseau Docker mutualisé entre plusieurs stacks (ex. Postgres partagé) déclaré `external: true` peut malgré tout être supprimé par un `docker compose down` quand aucun autre projet ne le revendique, avec perte de connectivité en cascade et conteneur recréé sans son mapping de ports.

Détail complet, règles opérationnelles et signal de détection : voir la section **« Réseau Docker partagé entre stacks — créer hors compose »** dans `90_debug_et_postmortem.md`.

- Contexte technique : Docker / réseau partagé / NUC — infra/postgres 22-04-2026