• Docs
  • Talk to an expert
Blog
Blog
BlogProduitÉtudes de casNouvellesPerspectives
Blog

C'est quoi un Dockerfile ? Un guide en langage simple

conteneursconfigurationdéploiementDevOps
19 novembre 2026
Partager
Cette page a été rédigée en anglais par nos experts, puis traduite par une IA pour vous y donner accès rapidement! Pour la version originale, c’est par ici.

En bref

  • Un Dockerfile est un fichier texte contenant des instructions pour créer une image de conteneur : une copie packagée d'une application avec tout ce dont elle a besoin pour fonctionner.
  • La création du Dockerfile génère une image, et l'exécution de cette image crée un conteneur. Un seul Dockerfile peut créer une image capable de faire tourner autant de conteneurs que tu veux.
  • Un Dockerfile typique choisit une image de départ, y copie le code de l'application, installe ses dépendances et indique quelle commande lance l'application.
  • L’ordre des instructions influe sur la rapidité des recréations, car Docker réutilise les étapes qui n’ont pas changé.
  • Tu as besoin d’un fichier Dockerfile lorsque tu packages toi-même ton application sous forme de conteneur. Certaines plateformes d’hébergement créent le conteneur à ta place à partir d’un fichier de configuration.
  • Upsun Cloud en fait partie : il construit ton application à partir de .upsun/config.yaml, tu n’as donc pas besoin d’un Dockerfile pour ton application, et elle peut également exécuter des images Docker publiques toutes prêtes.

Un Dockerfile est un fichier en texte brut contenant des instructions étape par étape pour créer une image de conteneur. Considère-le comme une recette : il indique par quoi commencer, quoi ajouter et comment exécuter le résultat, pour que n’importe qui puisse produire exactement le même paquet d’application.

Si tu as ouvert un projet et trouvé un fichier simplement nommé Dockerfile, sans extension, ce guide t'explique comment le lire. Il explique comment les fichiers Dockerfile, les images et les conteneurs s’articulent entre eux, te guide à travers un exemple concret et t’explique quand tu dois en créer un.

Dockerfile, image et conteneur : comment ils s’articulent

Point clé : un Dockerfile, c’est la recette ; une image, c’est ce que la recette produit ; et un conteneur, c’est cette image en cours d’exécution.

Ces trois termes sont souvent utilisés ensemble, et on peut facilement les confondre.

Diagram: a Dockerfile is built into an image with docker build, and the image is run as a container with docker run.
TermeC’est quoiComparaison culinaire
DockerfileUn fichier texte contenant des instructionsLa recette
ImageUn instantané packagé et en lecture seule d’une appli et de tout ce dont elle a besoin : code, bibliothèques et outils systèmeUn lot de plats, préparés et surgelés
ConteneurUne copie exécutable d’une imageUn repas, réchauffé et servi

Tu crées un Dockerfile une seule fois pour obtenir une image, et tu peux exécuter cette image dans autant de conteneurs que tu le souhaites. Tous les conteneurs issus de la même image sont identiques au départ, et c’est justement le but : l’application se comporte de la même manière sur l’ordinateur portable d’un développeur, dans un pipeline de test et sur un serveur.

Les images sont également partageables. Les équipes les publient sur des registres tels que Docker Hub, afin que d’autres puissent les télécharger et les exécuter sans avoir à les créer. De nombreux fichiers Dockerfile partent de l’une de ces images publiées plutôt que de partir de zéro.

Exemple de fichier Dockerfile, expliqué

Point clé : de nombreux fichiers Dockerfile suivent la même structure : ils partent d’une image de base, ajoutent les dépendances et le code de l’application, puis indiquent comment la lancer.

Voici un fichier Dockerfile pour une petite application web Node.js :

FROM node:24-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]
LigneCe qu’elle fait
FROM node:24-slimPart d’une image publiée sur laquelle Node.js 24 est déjà installé. slim C'est une variante plus légère avec moins d'outils supplémentaires
WORKDIR /appUtilise le /app dossier à l'intérieur de l'image pour tout ce qui suit
COPY package.json package-lock.json ./Copie uniquement les fichiers qui répertorient les dépendances de l'application
RUN npm ci --omit=devInstalle les versions exactes des dépendances indiquées dans le fichier lock, en laissant de côté les outils qui ne servent qu’au développement
COPY . .Copie le reste du code de l'appli dans l'image
EXPOSE 3000Note que l'appli écoute sur le port 3000. Ce document indique le port, mais celui-ci doit quand même être publié quand le conteneur est en cours d'exécution
CMD ["node", "server.js"]La commande qui lance l'appli quand le conteneur est en cours d'exécution

Copier les fichiers de dépendances séparément, avant le reste du code, c'est un choix délibéré. Docker construit une image par couches, une par instruction, et réutilise toute couche dont les entrées n'ont pas changé. Copier les fichiers de dépendances en premier signifie qu'une modification du code de l'appli ne déclenche pas une réinstallation complète de toutes les dépendances, ce qui rend les recompilations bien plus rapides. Notre guide Qu'est-ce qu'un fichier lock ? explique pourquoi ce fichier lock est important.

Le même principe s'applique à d'autres langages. Un Dockerfile Python pourrait commencer par FROM python:3.13-slim et s’installer à partir d’un fichier « requirements » ou « lock », tandis qu’un fichier Dockerfile PHP pourrait partir d’une php et exécuter Composer.

Les instructions les plus courantes dans un Dockerfile

À retenir : une douzaine d’instructions suffisent pour couvrir les Dockerfiles que tu es susceptible de lire. Chacune correspond à un seul mot en majuscules au début d’une ligne.

InstructionCe qu’elle fait
FROMDéfinit l’image de départ. Chaque fichier Dockerfile commence par cette instruction
WORKDIRDéfinit le dossier à l'intérieur de l'image où les instructions suivantes s'exécuteront
COPYCopie les fichiers de ton projet dans l'image
ADDComme COPY, mais peut aussi décompresser des archives et télécharger depuis des adresses web. Utilise COPY sauf si tu as besoin de ces fonctionnalités supplémentaires
RUNExécute une commande pendant la création de l'image, comme l'installation de paquets
ENVDéfinit une variable d'environnement à l'intérieur de l'image
ARGDéfinit une valeur qui n’est disponible que pendant la création de l’image
EXPOSEIndique sur quel port l'application écoute
USERPasse à un autre utilisateur pour les instructions et commandes qui suivent
CMDDéfinit la commande par défaut qu’un conteneur exécute au démarrage. Elle peut être remplacée au moment de lancer le conteneur
ENTRYPOINTDéfinit le programme principal que le conteneur exécute systématiquement. Tout ce qui se trouve dans CMD lui est transmis en tant qu’options supplémentaires

La différence entre RUN et CMD sème la confusion chez les gens. RUN se produit une seule fois, pendant la construction de l'image. CMD se produit à chaque fois qu’un conteneur démarre à partir de cette image.

Création et exécution : les commandes

Point clé : docker build transforme un Dockerfile en image, et docker run lance un conteneur à partir de celle-ci.

Exécute ces commandes depuis le dossier qui contient le Dockerfile :

CommandeCe que ça fait
docker build -t myapp .Construit une image à partir du fichier Dockerfile de ce dossier et la nomme « myapp ». Le point signifie « ce dossier »
docker run -p 3000:3000 myappLance un conteneur à partir de l'image et rend le port 3000 accessible à l'adresse localhost:3000
docker run -d -p 3000:3000 myappLa même chose, mais en arrière-plan
docker imagesAffiche la liste des images présentes sur ton ordinateur
docker psAffiche la liste des conteneurs en cours d'exécution
docker stop <container>Arrête un conteneur en cours d'exécution
docker push <name>Télécharge une image vers un registre pour que d'autres puissent l'utiliser

Quand une appli a besoin d’autres services en parallèle, comme une base de données, démarrer chaque conteneur à la main docker run devient vite fastidieux. C’est là que Docker Compose entre en jeu. Notre guide « Comment utiliser les fichiers .env avec Docker Compose » t’explique comment démarrer plusieurs conteneurs en même temps.

Erreurs courantes et comment les éviter

Point clé : les erreurs les plus coûteuses dans un Dockerfile consistent à intégrer des secrets dans les images ou à les rendre lentes et surchargées. Quelques bonnes habitudes permettent de les éviter.

Copier des secrets dans l’image

Une ligne comme COPY . . copie tout ce qui se trouve dans le dossier, y compris un .env fichier rempli de mots de passe, à moins que tu ne dises le contraire à Docker. N’importe qui qui récupère l’image peut lire ces fichiers. Ajoute un .dockerignore fichier à côté du Dockerfile. Ça fonctionne comme un fichier .gitignore et ça empêche certains fichiers d’être inclus dans l’image :

.env
.git
node_modules

Il en va de même pour les mots de passe définis avec ENV ou ARG dans le Dockerfile : ils restent lisibles dans l’image. Transmets plutôt les secrets au moment de l’exécution du conteneur. Nos guides Qu’est-ce qu’un fichier .gitignore ? et Que sont les variables d’environnement ? abordent ces deux aspects.

Reconstructions lentes

Copier tout le code avant d’installer les dépendances signifie que chaque petite modification du code entraîne la réinstallation de tout. Copie d’abord les fichiers de dépendances et installe-les, puis copie le reste, comme dans l’exemple ci-dessus.

Images trop volumineuses

Partir d’une image de base complète fait charger des outils que l’appli n’utilise jamais, ce qui ralentit le téléchargement des images et donne plus de matière aux attaquants. Utilise une variante allégée quand elle existe. Pour les applis qui n’ont besoin d’outils de compilation que pendant la compilation, une compilation en plusieurs étapes utilise une image pour compiler l’appli et ne copie que le résultat dans une deuxième image, plus petite.

Utilisation d’une version flottante

FROM node:latest ou FROM node utilise la version la plus récente le jour de la compilation ; ainsi, un même Dockerfile peut produire des images différentes à un mois d’intervalle. Fixe une version, par exemple node:24-slim.

Exécution en tant qu’administrateur

Par défaut, les conteneurs s’exécutent en tant qu’utilisateur root, qui dispose d’un contrôle total à l’intérieur du conteneur. De nombreuses images de base officielles incluent un utilisateur standard, et passer à celui-ci avec USER limite les dégâts si jamais l'application venait à être compromise.

L'application n'est pas accessible depuis l'extérieur du conteneur

Une application qui n'écoute que sur 127.0.0.1 ou localhost à l’intérieur d’un conteneur ne peut pas être accessible depuis ton navigateur, même si le port est publié. Configure-la pour qu’elle écoute sur 0.0.0.0, ce qui signifie « accepter les connexions de n'importe où ».

Quand tu as besoin d'un Dockerfile, et quand une plateforme construit le conteneur pour toi

Point clé : rédige un Dockerfile lorsque tu packages ta propre application sous forme de conteneur. Certaines plateformes d’hébergement, dont Upsun Cloud, construisent le conteneur pour toi à partir d’un fichier de configuration.

Tu auras besoin d’un Dockerfile lorsque :

  • Tu déploies sur un service qui exécute les conteneurs que tu fournis, comme Kubernetes ou un service d’hébergement de conteneurs
  • Tu souhaites publier ton application sous forme d’image que d’autres peuvent télécharger et exécuter
  • Ton environnement de développement local exécute l’application dans un conteneur, souvent avec Docker Compose

Tu n’en auras peut-être pas besoin si ta plateforme d’hébergement se charge de créer l’application pour toi. Au lieu d’écrire toi-même les étapes de création, tu décris simplement ce dont l’application a besoin, comme sa version de langage et comment la démarrer, et la plateforme génère le conteneur.

Comment ça marche sur Upsun Cloud

Upsun Cloud compile ton application à partir de .upsun/config.yaml, tu n’as donc pas besoin d’écrire de Dockerfile. Il existe trois façons de décrire une application :

Type d’applicationCe que tu décrisIdéal pour
Image à exécution uniqueUn seul langage et une seule version, par exemple nodejs:26, avec des commandes de compilation et de démarrageApplications web classiques
Image modulablePlusieurs environnements d'exécution et outils dans un seul conteneur, choisis parmi plus de 120 000 paquets de la collection NixApplications nécessitant des outils système supplémentaires ou plusieurs langages
Image Docker (type: docker:1)Une image publique toute prête, qu’Upsun Cloud exécute telle quelleDes outils auto-hébergés qui fournissent déjà une image officielle

Pour l’application Node.js de l’exemple ci-dessus, l’équivalent sur Upsun Cloud tient en quelques lignes :

applications:
  app:
    type: "nodejs:26"
    web:
      commands:
        start: "node server.js"

Pour les applications Node.js, la configuration par défaut d’Upsun Cloud installe tes dépendances avec npm ; les étapes décrites dans ton Dockerfile s’exécutent donc sans que tu aies à t’en occuper.

L’option d’image Docker comporte des limites qu’il est bon de connaître. Upsun Cloud ne génère pas de Dockerfile à partir de ton dépôt pour ce type d’application. Il exécute une image qui a déjà été construite et publiée. Les hooks de build ne sont pas pris en charge ; c’est à toi de mettre à jour l’image lorsque son éditeur publie des correctifs de sécurité, et la documentation mentionne Meilisearch et n8n comme les images vérifiées à ce jour.

Tu peux déployer gratuitement sur Upsun Cloud pendant 15 jours, sans avoir besoin de carte bancaire, ou découvrir comment l’automatisation basée sur Git construit ton application à partir de la configuration.

Foire aux questions

Quelle est la différence entre un Dockerfile et une image ?

Un Dockerfile est un fichier texte contenant des instructions. Une image, c’est ce que tu obtiens quand tu exécutes ces instructions : un instantané de l’application, packagé et prêt à l’emploi.

Quelle est la différence entre un Dockerfile et un fichier docker-compose.yml ?

Un Dockerfile décrit comment créer une image. Un fichier compose décrit comment exécuter plusieurs conteneurs ensemble, comme une application, une base de données et un cache. Un fichier compose utilise souvent un Dockerfile pour créer l'image de l'application elle-même.

Est-ce qu’un Dockerfile a besoin d’une extension de fichier ?

Non. Le fichier s’appelle généralement exactement Dockerfile, avec un D majuscule et sans extension. Tu peux utiliser un autre nom et y faire référence avec docker build -f.

Quelle est la différence entre CMD et ENTRYPOINT ?

Les deux définissent ce que le conteneur exécute au démarrage. CMD est une valeur par défaut facile à remplacer au démarrage du conteneur. ENTRYPOINT définit le programme principal, et tout ce qui se trouve dans CMD lui est transmis en tant qu’options supplémentaires.

C'est quoi un fichier .dockerignore ?

C’est un fichier qui répertorie ce que Docker doit ignorer lors de la copie de ton projet dans une image, comme les fichiers .env, le dossier .git et les dépendances installées. Ça fonctionne un peu comme un fichier .gitignore.

Ai-je besoin d’un Dockerfile pour déployer mon application ?

Ça dépend de l'endroit où tu le déploies. Les plateformes qui exécutent les conteneurs que tu fournis en ont besoin. Celles qui construisent ton application à partir d'une configuration, comme Upsun Cloud, n'en ont pas besoin.

Restez informé

Abonnez-vous à notre newsletter mensuelle pour les dernières mises à jour et nouvelles.

Déployez en toute liberté.
Essayez Upsun gratuitement.

Développez avec DispatchDéployez avec Cloud