
En bref
|
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.
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.
| Terme | C’est quoi | Comparaison culinaire |
|---|---|---|
| Dockerfile | Un fichier texte contenant des instructions | La recette |
| Image | Un instantané packagé et en lecture seule d’une appli et de tout ce dont elle a besoin : code, bibliothèques et outils système | Un lot de plats, préparés et surgelés |
| Conteneur | Une copie exécutable d’une image | Un 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.
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"]| Ligne | Ce qu’elle fait |
|---|---|
FROM node:24-slim | Part 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 /app | Utilise 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=dev | Installe 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 3000 | Note 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.
À 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.
| Instruction | Ce qu’elle fait |
|---|---|
FROM | Définit l’image de départ. Chaque fichier Dockerfile commence par cette instruction |
WORKDIR | Définit le dossier à l'intérieur de l'image où les instructions suivantes s'exécuteront |
COPY | Copie les fichiers de ton projet dans l'image |
ADD | Comme 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 |
RUN | Exécute une commande pendant la création de l'image, comme l'installation de paquets |
ENV | Définit une variable d'environnement à l'intérieur de l'image |
ARG | Définit une valeur qui n’est disponible que pendant la création de l’image |
EXPOSE | Indique sur quel port l'application écoute |
USER | Passe à un autre utilisateur pour les instructions et commandes qui suivent |
CMD | Dé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 |
ENTRYPOINT | Dé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.
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 :
| Commande | Ce 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 myapp | Lance un conteneur à partir de l'image et rend le port 3000 accessible à l'adresse localhost:3000 |
docker run -d -p 3000:3000 myapp | La même chose, mais en arrière-plan |
docker images | Affiche la liste des images présentes sur ton ordinateur |
docker ps | Affiche 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.
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.
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_modulesIl 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.
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.
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.
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.
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.
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ù ».
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 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.
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’application | Ce que tu décris | Idéal pour |
|---|---|---|
| Image à exécution unique | Un seul langage et une seule version, par exemple nodejs:26, avec des commandes de compilation et de démarrage | Applications web classiques |
| Image modulable | Plusieurs environnements d'exécution et outils dans un seul conteneur, choisis parmi plus de 120 000 paquets de la collection Nix | Applications 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 quelle | Des 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.
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.
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.
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.
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 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.
Ç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.
