Docker init : comment initialiser un projet avec Docker (guide pas à pas)

Pour une raison ou une autre, lancer un nouveau projet avec Docker prend toujours plus de temps que prévu.

Vous cherchez un modèle sur Google, vous le collez, vous modifiez deux ou trois lignes et vous croisez les doigts. La build échoue, alors vous ajustez et vous recommencez jusqu'à ce que ça marche. Chaque nouveau projet débute pareil : un fichier vide et le vague souvenir de ce qui avait fonctionné la dernière fois. Le problème vient du setup, pas de Docker.

La bonne nouvelle, c'est que docker init règle ce souci. Il s'agit d'une commande CLI qui détecte le type de projet et génère un Dockerfile, un .dockerignore et un fichier Compose.

Dans cet article, je vous montre comment fonctionne docker init, comment l'utiliser pas à pas sur un vrai projet Python, et quand c'est l'outil adéquat.

Vous débutez totalement avec Docker et la conteneurisation ? Découvrez pourquoi c'est un incontournable de la boîte à outils des pros de la donnée avec notre cours Introduction to Docker.

Qu'est-ce que Docker init

docker init est un outil en ligne de commande qui met en place la configuration Docker de votre projet. Il génère les fichiers dont vous avez besoin pour conteneuriser votre application. Plus besoin de modèles ni de copier-coller.

Il produit trois fichiers :

• Dockerfile – définit la façon dont l'image de votre conteneur est construite
• .dockerignore – indique à Docker quels fichiers exclure du contexte de build
• compose.yml – facultatif, mais pratique pour les architectures multi-services

Le point fort : la détection automatique du projet. docker init analyse la structure et identifie votre stack – Python, Node.js, Go, etc. – puis génère des fichiers adaptés à cette stack, pas un modèle générique.

Ce n'est pas un outil de déploiement et il ne gère pas vos conteneurs en production. Il initialise la configuration pour que vous puissiez vous concentrer sur l'essentiel.

Comment fonctionne Docker init

docker init suit un flux en quatre étapes à chaque exécution.

D'abord, vous lancez docker init dans le dossier du projet. Docker scanne le répertoire, détecte le type de projet et choisit le bon modèle de configuration. Ensuite, il vous guide via quelques invites interactives : le port utilisé par l'application, la commande de démarrage, etc. Une fois vos réponses saisies, il génère les fichiers.

Le tout prend moins d'une minute.

Les questions sont simples et nécessitent rarement des explications. Vous pouvez valider les valeurs par défaut avec Entrée ou saisir les vôtres si besoin.

Voici ce que vous verrez au premier lancement :

Écran de configuration Docker init

Passons maintenant en détail.

Comment utiliser Docker init pas à pas

Voici la démarche pour passer d'un dossier de projet à un conteneur en cours d'exécution.

Étape 1 : accédez au répertoire de votre projet

Ouvrez votre terminal et placez-vous à la racine du projet – le dossier qui contient le code de votre application.

cd /path/to/your/project

docker init génère les fichiers par rapport au répertoire courant : assurez-vous d'être au bon endroit avant de continuer.

Étape 2 : lancez Docker init

Exécutez la commande suivante :

docker init

Docker scannera votre dossier, détectera votre stack et ouvrira l'assistant interactif.

Étape 3 : répondez aux invites

docker init vous posera quelques questions :

• Plateforme applicative – le langage ou framework utilisé (Python, Node.js, Go, etc.)
• Port – le port écouté par votre application
• Commande de démarrage – la commande à exécuter pour lancer l'application

Acceptez les valeurs par défaut avec Entrée ou saisissez les vôtres. Si docker init détecte votre stack, les défauts suffisent généralement pour démarrer.

Étape 4 : vérifiez les fichiers générés

Après vos réponses, docker init écrit trois fichiers dans le dossier du projet :

.
├── Dockerfile
├── .dockerignore
└── compose.yaml

Ouvrez-les et parcourez-les. Des commentaires expliquent chaque ligne : prenez quelques minutes pour comprendre ce qui a été créé avant de builder quoi que ce soit.

Étape 5 : construisez et exécutez votre conteneur

Construisez et lancez avec Docker Compose :

docker compose up --build

L'option --build indique à Docker de construire l'image à partir du Dockerfile avant de démarrer le conteneur. Une fois lancé, votre application doit être accessible sur le port spécifié à l'étape 3.

Types de projets pris en charge par Docker init

docker init prend en charge dès l'installation les stacks applicatives les plus courantes. En voici quelques-unes :

• Python
• Node.js
• Go
• Java
• .NET

La détection est automatique. Au lancement, docker init recherche des fichiers propres à chaque langage – comme requirements.txt pour Python ou package.json pour Node.js – et choisit le bon modèle en conséquence.

Chaque modèle est adapté à la stack. Un projet Python utilisera une image de base, des commandes d'installation et de démarrage différentes d'un projet Go. Ce n'est pas un Dockerfile unique avec une variable de langage : la structure varie selon ce que vous construisez.

Si docker init ne parvient pas à détecter la stack, vous pourrez la sélectionner manuellement dans la liste.

Fichiers générés par Docker init

docker init génère trois fichiers, chacun ayant un rôle précis.

Dockerfile

Le Dockerfile définit comment Docker construit l'image de votre conteneur : image de base, installation des dépendances, commande de démarrage, etc.

Voici un exemple de Dockerfile Python généré :

FROM python:3.14-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

Relisez ce fichier avant de builder. La sortie générée constitue une bonne base, mais vous devrez peut-être l'ajuster : ajouter des variables d'environnement, verrouiller la version de l'image de base, etc.

.dockerignore

Le fichier .dockerignore indique à Docker quels fichiers exclure du contexte de build, c'est-à-dire l'ensemble des fichiers envoyés au moteur de build lors de la création de l'image.

Sans lui, Docker copierait tout le dossier du projet dans l'image, y compris .git, node_modules ou des fichiers locaux de config inutiles en production. Cela gonfle l'image et peut exposer des fichiers non souhaités.

Un .dockerignore typique ressemble à ceci :

.git
.env
__pycache__
*.pyc
node_modules

Fichier Docker Compose

Le fichier compose.yaml sert à exécuter des architectures multi-conteneurs. Il définit vos services, ports, volumes et la manière dont les conteneurs communiquent entre eux.

Pour une application simple à conteneur unique, vous n'en aurez pas forcément besoin. Mais si votre projet comprend une base de données, un cache ou tout autre service annexe, le fichier Compose est l'endroit où tout configurer au même endroit.

Exemple : utiliser Docker init avec un projet Python

Lançons docker init sur un vrai projet. Je prends un mini FastAPI avec une unique route en exemple.

Structure du projet avant docker init :

my-fastapi-app/
├── app.py
└── requirements.txt

app.py expose une simple route Hello World :

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

Et requirements.txt liste ces deux dépendances :

fastapi
uvicorn

Exécuter docker init

Commencez par vous placer dans le dossier du projet et lancez :

docker init

Projet détecté par Docker init

docker init détecte Python via requirements.txt et vous pose quelques questions. Voici à quoi ressemblent les invites et quoi répondre :

Invites Docker init pour un projet Python

Ce qui est généré

Après réponse, votre dossier de projet ressemble à ceci :

Nouvelle structure de dossier

Trois nouveaux fichiers sont présents. Examinons-les.

Le Dockerfile

# syntax=docker/dockerfile:1

ARG PYTHON_VERSION=3.14
FROM python:${PYTHON_VERSION}-slim as base

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

WORKDIR /app

ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser

RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=bind,source=requirements.txt,target=requirements.txt \
    python -m pip install -r requirements.txt

USER appuser

COPY . .

EXPOSE 8000

CMD uvicorn 'app:app' --host=0.0.0.0 --port=8000

Quelques points à noter : PYTHONDONTWRITEBYTECODE=1 empêche Python d'écrire des fichiers .pyc sur disque, et PYTHONUNBUFFERED=1 garantit l'affichage immédiat des logs au lieu de les mettre en buffer : deux bons défauts pour une app conteneurisée.

Le bloc adduser crée un utilisateur non privilégié appuser pour exécuter l'application. Par défaut, un conteneur Docker tourne en root, ce qui pose un risque de sécurité. Exécuter en non-root limite l'impact d'une compromission.

L'option --mount=type=cache lors de l'installation pip demande à Docker de mettre en cache les paquets entre les builds, évitant de tout retélécharger et accélérant les builds suivantes.

Le .dockerignore

**/.DS_Store
**/__pycache__
**/.venv
**/.env
**/.git
**/.gitignore
**/node_modules
**/Dockerfile*
**/compose.y*ml
README.md

Le .dockerignore exclut les fichiers qui n'ont rien à faire dans l'image. Les fichiers d'environnement locaux (.env), les dossiers de versioning (.git) ou les caches Python (__pycache__) sont ignorés. Le Dockerfile et compose.yaml sont également exclus : Docker n'en a pas besoin à l'intérieur de l'image qu'il construit.

Le compose.yaml

services:
  server:
    build:
      context: .
    ports:
      - 8000:8000

Le fichier Compose définit votre app comme un service nommé server, la build à partir du Dockerfile courant, et mappe le port 8000 de l'hôte vers le 8000 du conteneur.

Les trois fichiers générés contiennent des commentaires que j'ai retirés ici pour plus de lisibilité.

Exécutez docker compose up --build et votre app FastAPI sera disponible sur http://localhost:8000.

Application FastAPI exécutée dans un conteneur

Docker init vs configuration manuelle d'un Dockerfile

Les deux approches mènent à un Dockerfile fonctionnel : tout dépend du niveau de contrôle souhaité et de la vitesse à laquelle vous voulez avancer.

Docker init

docker init est l'option la plus rapide. Quelques invites, et vous obtenez une configuration opérationnelle et raisonnablement sûre en moins d'une minute. Les fichiers suivent les bonnes pratiques Docker – utilisateur non-root, cache de build, motifs .dockerignore pertinents – vous évitant de partir de zéro.

C'est idéal pour démarrer un projet, intégrer un collègue ou poser une base solide sans s'attarder sur le boilerplate.

La question, c'est la flexibilité. Les modèles couvrent bien les stacks courantes, mais cela reste des modèles. Si votre projet a une structure atypique ou des besoins de build spécifiques, vous atteindrez les limites de docker init.

Configuration manuelle

Écrire votre Dockerfile à la main vous donne le contrôle total sur chaque couche, instruction et décision de build. Vous pouvez mettre en place des builds multi-étapes pour minimiser la taille, utiliser des images de base personnalisées ou affiner le cache à un niveau que docker init ne prévoit pas.

Mais il faut savoir ce que l'on fait. Un Dockerfile mal écrit peut produire des images volumineuses, introduire des failles de sécurité ou échouer de façon difficile à diagnostiquer, surtout sans expérience.

Que choisir ?

Voici une façon simple de voir les choses :

Comparaison Docker init vs configuration manuelle

Une bonne approche consiste à démarrer avec docker init, puis à affiner manuellement au fur et à mesure que vos besoins évoluent.

Quand utiliser Docker init

docker init n'est pas l'outil idéal en toute circonstance. Voici quand l'utiliser, et quand l'éviter.

Privilégiez docker init lorsque :

• Vous lancez un nouveau projet : votre configuration Docker est en place en moins d'une minute, et vous pouvez vous concentrer sur le code plutôt que sur la conteneurisation

• Vous apprenez Docker : les fichiers générés sont bien commentés et suivent les bonnes pratiques : c'est un meilleur point de départ qu'un snippet trouvé au hasard

• Vous prototypez : quand vous avez besoin rapidement d'un environnement conteneurisé sans optimiser la build, docker init vous livre quelque chose d'opérationnel

• Vous standardisez au sein d'une équipe : plutôt que chacun écrive son propre Dockerfile, docker init fournit une base cohérente avec la même structure et les mêmes défauts

En revanche, évitez docker init si :

• Vous avez besoin de builds multi-étapes : pour optimiser la taille en dissociant compilation et exécution, il faudra l'écrire vous-même. Le Dockerfile généré est monotétape

• Vos exigences de production sont complexes : images de base sur mesure, stratégies de cache avancées, structures non standards : docker init ne peut pas tout prévoir. Vous perdrez du temps à contourner la génération plutôt qu'à écrire directement votre configuration

En bref, docker init est un point de départ. Utilisez-le pour décoller, puis éditez les fichiers au fur et à mesure.

Limites de Docker init

Avec la croissance du projet, certaines limites apparaissent. En voici quelques-unes.

Les fichiers générés sont basés sur des modèles. Ils couvrent les cas les plus courants pour chaque stack, ce qui fonctionne bien pour des projets standards et moins bien en dehors de ce cadre. Si votre structure est atypique, il se peut que les fichiers ne la prennent pas en compte.

Autre limite fréquente : un ajustement manuel est presque toujours nécessaire. Les défauts sont bons, mais restent des défauts. Vous devrez probablement ajuster la version d'image de base, affiner des variables d'environnement ou modifier la commande de démarrage. Considérez ces fichiers comme un premier jet.

docker init ne gère pas non plus les schémas de build avancés. Les builds multi-étapes, arguments de build personnalisés, logiques conditionnelles et autres techniques pour des images de production sortent du périmètre de l'outil. Si vous en avez besoin, vous écrirez de toute façon le Dockerfile vous-même.

Rien de tout cela ne rend docker init mauvais. Il faut juste en attendre ce qu'il offre : il supprime la page blanche, sans remplacer la compréhension de votre Dockerfile.

Bonnes pratiques après avoir utilisé Docker init

Les fichiers générés par docker init sont une base. Voici les étapes pour les rendre prêts pour la production.

• Passez en revue les fichiers générés : lisez le Dockerfile, le .dockerignore et le compose.yaml ligne par ligne. Les commentaires aident ; comprenez avant d'empiler de nouvelles couches

• Optimisez la taille de l'image : l'image de base par défaut python:3.x-slim est déjà légère. Allez plus loin en étoffant votre .dockerignore et en évitant de copier des fichiers inutiles dans l'image

• Externalisez secrets et valeurs liées à l'environnement : ne codez pas en dur les clés API, URLs de base de données ou flags d'environnement dans le Dockerfile. Utilisez des variables d'environnement, un fichier .env en local ou la gestion des secrets de votre plateforme de déploiement

• Testez en local avant tout push : lancez docker compose up --build et vérifiez que l'app se comporte identiquement dans et hors conteneur. Consultez les logs, testez les endpoints et confirmez le mapping de ports

• Affinez les étapes de build en grandissant : le Dockerfile généré installe les dépendances en une seule couche. Avec le temps, pensez à l'ordre des couches : placez tôt ce qui change peu pour tirer parti du cache. Si vos temps de build augmentent, commencez par là

Problèmes courants et dépannage

Comme souvent en tech, quelques couacs peuvent survenir. Voici quoi vérifier et comment corriger.

Mauvaise détection du projet

Si docker init choisit la mauvaise stack, il génèrera des fichiers inadéquats. Cela arrive souvent dans des dossiers mélanges de langages ou lorsqu'il manque le fichier attendu – requirements.txt pour Python, package.json pour Node.js, etc.

Quand l'assistant vous demande la plateforme, sélectionnez simplement la bonne au lieu d'accepter la détection par défaut.

Conflits de ports

Si le conteneur démarre mais que vous n'atteignez pas l'app, ou si Docker signale qu'un port est déjà utilisé, un autre processus occupe probablement ce port.

Trouvez et arrêtez le processus en conflit, ou modifiez le port côté hôte dans compose.yaml :

ports:
  - 8001:8000  # mappe le port 8001 de l'hôte vers le 8000 du conteneur

La partie gauche est le port sur votre machine. La droite doit correspondre au port écouté dans le conteneur.

Dépendances manquantes

Si la build réussit mais que le conteneur plante au démarrage, il manque souvent des dépendances. Vérifiez que votre requirements.txt (ou équivalent) est à jour. Si vous avez ajouté un package en local sans l'y inscrire, le conteneur ne l'aura pas.

Consultez les erreurs avec docker compose logs :

docker compose logs

Le message d'erreur indique en général le package manquant.

Le conteneur ne démarre pas

Si le conteneur ne démarre pas du tout, le problème vient presque toujours de la ligne CMD du Dockerfile. Vérifiez que la commande de démarrage correspond à la façon dont vous lancez l'app.

Pour l'exemple FastAPI, elle doit ressembler à ceci :

CMD uvicorn 'app:app' --host=0.0.0.0 --port=8000

Si le nom du fichier d'entrée diffère ou si le chemin du module est faux, le conteneur sortira. Corrigez CMD, rebuild avec docker compose up --build et revérifiez les logs.

Conclusion

docker init ne remplace pas une vraie maîtrise de Docker, mais il vous épargne la page blanche.

En une seule commande, vous obtenez un Dockerfile, un .dockerignore et un compose.yml opérationnels, conformes aux bonnes pratiques Docker. C'est une excellente base pour tout nouveau projet, bien meilleure qu'un modèle copié-collé depuis Stack Overflow ou ChatGPT.

Ne vous arrêtez pas là pour autant. Ces fichiers sont faits pour être édités : relisez-les, affinez les étapes de build, verrouillez la version de l'image de base et ajoutez vos variables d'environnement. Plus votre projet grandit, plus vous vous éloignerez des défauts.

Si vous maîtrisez les fondamentaux de Docker, la suite logique consiste à apprendre les builds multi-étapes, les outils réseau et Docker Compose – tout cela est couvert dans notre cours Intermediate Docker .