Profils Docker Compose, fichiers d'override et précédence des environnements : guide pratique

Introduction

Docker Compose profiles, override files, et environment precedence sont cruciaux car lancer un conteneur de production est simple, mais l'exploiter de manière cohérente l'est beaucoup moins. Un guide utile doit montrer quoi configurer, quelle commande prouve que la configuration fonctionne, et à quoi ressemble l'échec quand le montage est incorrect.

Cet article se concentre sur Docker Compose profiles pour une petite entreprise ou un responsable marketing technique. Il relie le sujet aux notions docker compose override, Compose env_file, .env precedence et configuration drift afin de passer du concept à la vérification locale.

Notre objectif est pratique : comprendre les pièces mobiles, les tester en local, et éviter les surprises quand on réutilise le même motif en CI/CD ou en environnement de type production.

Vue d'ensemble du workflow

Pour Docker Compose profiles, commencez par identifier la ressource impliquée, le changement de configuration qui l'affecte, et la commande qui prouve que le montage fonctionne. Gardez le workflow pragmatique : configurez un élément, vérifiez l'état observé, puis documentez ce qui casse quand la configuration est manquante, erronée, ou transposée dans un environnement proche de la production.

Dans la pratique, c'est ici que les équipes découvrent les hypothèses cachées. Chemins locaux, tags d'image, noms de réseau, fichiers d'environnement, limites de ressources et permissions varient fortement entre laptops, runners et hôtes de production. Rendre explicites ces hypothèses avant de miser sur l'assemblage évite de nombreux faux positifs.

Vérifications Docker utiles pour le workflow :

• docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" pour voir ce qui tourne.
• docker logs <container> --tail 100 pour lire les derniers échecs.
• docker inspect <container> pour les montages, réseaux, variables et healthchecks.

Pour les projets Compose :

• docker compose ps
• docker compose logs -f <service>
• docker compose exec <service> sh pour diagnostiquer sans changer l'image.

Quand des données sont impliquées, confirmez l'emplacement avant de changer les conteneurs. Un volume nommé comme app_data:/var/lib/app est géré par Docker et se réutilise facilement entre rebuilds. Un bind mount ./data:/var/lib/app mappe directement un répertoire hôte : utile en dev, mais il peut exposer des problèmes de permissions, de portabilité et de sauvegarde si le même chemin n'existe pas ailleurs.

Un test local proche de la production doit inclure un test de redémarrage : arrêtez le conteneur, recréez-le, et confirmez que l'application voit toujours les fichiers attendus. Si les données disparaissent, le service écrivait probablement dans le filesystem éphémère du conteneur au lieu d'un volume ou d'un montage.

Plan pilote local

Objectif : démontrer, pas simplement décrire. Nous allons relier Docker Compose profiles, docker compose override, Compose env_file, .env precedence et montrer comment éviter la configuration drift entre variantes locales et environnements staging-like.

1. Fichiers Compose et override

Fichier de base :

author: example
version: "3.9"
services:
  web:
    build: ./app
    ports:
      - "8080:8080"
    environment:
      - APP_ENV=${APP_ENV:-development}
    volumes:
      - app_data:/var/lib/app
volumes:
  app_data:

Fichier local docker-compose.override.yml :

services:
  web:
    # Bind mount pour accélérer l'itération locale
    volumes:
      - ./data:/var/lib/app
    environment:
      - APP_DEBUG=true

Ce fichier d'override est fusionné automatiquement s'il est présent et ne pollue pas la base partagée. Pour contrôler explicitement la fusion :

docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

Rappel : dans l'ordre des -f, le dernier fichier a la précédence (docker compose override contrôlé).

1. Docker Compose profiles (services optionnels)

Définissez des profils pour les services non indispensables en permanence :

services:
  web:
    build: ./app
    ports: ["8080:8080"]
  worker:
    image: myorg/worker: latest
    profiles: ["jobs"]
  db:
    image: postgres:16
    profiles: ["local-db"]
    environment:
      - POSTGRES_PASSWORD=secret

Activez-les à la demande :

COMPOSE_PROFILES=jobs, local-db docker compose up -d
# ou
docker compose --profile jobs --profile local-db up -d

Sans activation, web démarre (pas de profil), tandis que worker et db sont ignorés.

1. .env precedence et Compose env_file

Distinguez :

• Substitution de variables du fichier Compose (".env precedence") : .env fournit des valeurs par défaut à ${VAR}. Une variable exportée dans le shell l'emporte sur .env pour la substitution.
• Variables dans le conteneur (Compose env_file) : env_file charge des paires KEY=VALUE. La clé environment a priorité sur env_file en cas de conflit.

Exemple :

# .env
APP_ENV=staging
IMAGE_TAG=latest

services:
  web:
    image: myorg/app:${IMAGE_TAG}
    env_file:
      - web.env
    environment:
      - APP_ENV=${APP_ENV}

# web.env
APP_ENV=production
FEATURE_FLAG=true

Commande :

export IMAGE_TAG=v2
docker compose up -d --build

Résultat :

• L'image résolue est myorg/app: v2 (la variable du shell prime sur .env).
• À l'intérieur du conteneur, APP_ENV provient de environment et écrase web.env.
• FEATURE_FLAG=true est importé via env_file (non redéfini ailleurs).

1. Variantes locales et contrôle de la configuration drift

Limitez l'override local aux éléments volatils (bind mounts, niveau de logs, ports). Conservez la topologie (services, réseaux, volumes nommés) dans le fichier principal. Utilisez des profils pour activer des composants de développement (ex. local-db) sans modifier la base commune. Pour les secrets ou variables partagées, stockez-les dans des env_file réutilisés et ne surchagez que ce qui est strictement nécessaire dans environment côté local.

Checklist rapide anti-drift :

• Une seule source de vérité (docker-compose.yml) pour la topologie.
• docker-compose.override.yml minimal, reversible et spécifique au local.
• Profils explicites pour les services optionnels.
• env_file commun + surcharges ciblées via environment.
• Tests de redémarrage et d'inspection après chaque changement significatif.

1. Dockerfile examples (multi-stage)

# build stage
FROM node:20-alpine AS build
WORKDIR /src
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# runtime stage
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /src/dist /app
EXPOSE 8080
CMD ["node", "server.js"]

Côté Compose, choisissez build: ./app pour un cycle local rapide ; basculez vers image: myorg/app:${IMAGE_TAG} pour coller à un déploiement plus proche de la production, en pilotant IMAGE_TAG avec la .env precedence.

1. Commandes de validation et troubleshooting

• Démarrer/mettre à jour :

docker compose up -d --pull=missing --build

• État :

docker compose ps

• Logs :

docker compose logs -f web

• Inspection des variables et fichiers :

docker compose exec web sh -lc 'env | sort && ls -al /var/lib/app'

• Test de persistance (production pitfalls fréquents) :

docker compose stop web
docker compose rm -f web
docker compose up -d web

Si les données manquent, remplacez le chemin par un volume nommé ou corrigez le bind mount. En cas d'erreurs de permissions, alignez UID/GID et l'utilisateur du processus dans le conteneur. Sur conflits de ports, ajustez le mapping dans l'override.

Conclusion

Docker Compose profiles, override files et environment precedence fonctionnent mieux quand l'équipe les traite comme un objet à tester, pas seulement à copier. La voie la plus sûre : garder des exemples petits, exécuter les commandes en local et confirmer le comportement attendu avant d'ajouter des services ou de l'automatisation.

Pour la suite, choisissez un service et documentez les commandes exactes pour le construire, l'exécuter, l'inspecter, l'arrêter et le recréer. Comparez le résultat avec vos workflows Docker Compose proches de la production afin que l'implémentation s'intègre à votre modèle d'exploitation. Un workflow fiable rend l'échec visible : logs faciles à trouver, données persistantes après rebuild, et un local testing assez proche de la production pour déceler tôt les erreurs.