Guide 03 / 3
Dockerfile & compose.yaml
Understand each instruction and its consequences on the build or at run time.
Explain the Dockerfile → image → container cycle and configure Compose services.
01 · How the files work together
A Dockerfile describes how to make an image; compose.yaml describes how to run the services. They are neither programming languages nor, strictly speaking, the Docker Engine HTTP API.
Dockerfile
The recipe for building the image. Its instructions are processed mainly during docker build.
Example
Dockerfile → docker build → image
compose.yaml
A YAML declaration of services, volumes and networks. Compose interprets this configuration to create and run the containers.
Example
compose.yaml → docker compose up → services
Docker Engine API
The HTTP interface of the Docker daemon used by clients to drive the Engine. The words FROM, RUN and CMD are Dockerfile instructions, not calls to this API.
Example
La CLI peut interroger l’API du démon pour lister des conteneurs.
02 · Dockerfile instructions
Instructions are read in order during the build; some prepare the image, others define values used at launch.
FROM
Chooses the base image and starts a build stage. A base image already contains a minimal system or tools.
Example
FROM python:3.13-slim
Prefer an explicit, maintained reference.
RUN
Runs a command when building the image: installing a library, generating a file, preparing a folder. Its result becomes part of the image.
Example
RUN pip install --no-cache-dir -r requirements.txt
RUN does not start the server when the container is launched.
CMD
Defines the default command run when the container is launched, or arguments for ENTRYPOINT. A docker run command can replace it.
Example
CMD ["python", "app.py"]
Only the last CMD in the Dockerfile takes effect.
ENTRYPOINT
Determines the program to run when the container starts. This program generally becomes the main process (PID 1), for example the web server or the application script.
Example
ENTRYPOINT ["python", "app.py"]
CMD can complete ENTRYPOINT with arguments.
COPY
Copies files from the build context into the image. The destination is a path inside the image, not on the host machine.
Example
COPY ./src /app/src
ADD
Adds files and offers extra features (remote sources, local archives depending on the case). For a simple copy, prefer COPY.
Example
ADD archive.tar.gz /opt/app/
ADD is not a generic download command.
WORKDIR
Sets the working folder for the following instructions and the default command. It is created if necessary.
Example
WORKDIR /app
ENV
Defines a variable available during the following instructions and in containers based on the image.
Example
ENV APP_MODE=production
Do not put secrets in it.
ARG
Defines a value used during the build, possibly passed via --build-arg; it is not automatically a runtime environment variable.
Example
ARG APP_VERSION=1.0
EXPOSE
Documents the network port or ports on which the application is meant to listen. This informs readers and some tools, but does not make the service reachable from the host.
Example
EXPOSE 3000
To reach it from your computer: docker run -p 8080:3000 ...
USER
Defines the user used for the following instructions or startup. Running an application without root rights limits some risks.
Example
USER app
HEALTHCHECK
Defines a periodic test that indicates whether the application really works, beyond the mere presence of its process.
Example
HEALTHCHECK CMD wget -q -O - http://localhost:3000/health || exit 1
The program used for the test must be present in the image.
LABEL
Adds metadata as key=value pairs, useful for traceability.
Example
LABEL org.opencontainers.image.title="Mon API"
VOLUME
Declares a mount point intended for data. In practice, persistence is often configured in Docker Compose.
Example
VOLUME /data
SHELL
Changes the interpreter program used by shell-form instructions.
Example
SHELL ["/bin/sh", "-c"]
ONBUILD
Registers an instruction triggered when this image later serves as the base image of another Dockerfile.
Example
ONBUILD COPY . /app
.dockerignore
A file beside the build context that removes files from the context sent to the builder; it lets you exclude caches, local dependencies and sensitive data.
Example
node_modules
.git
.env
03 · compose.yaml keys
YAML indentation builds a hierarchy: services contains web and db; each service contains its settings. The names shown below are configuration keys, not commands.
name
The logical name of the Compose project, used to tell its resources apart from those of other projects.
Example
name: demo-web
services
The root section containing all the application's services. A service describes the image and configuration of its containers.
Example
services:
web:
image
The image to use: either pulled from a registry, or tied to the build result depending on the configuration.
Example
image: nginx:alpine
build
Tells Compose how to make an image. Can be a short path or a detailed object.
Example
build:
context: .
dockerfile: Dockerfile
context
The path of the files sent to the builder. The dot stands for the Compose project's directory. It is distinct from WORKDIR in the image.
Example
context: .
dockerfile
The path of an alternative build file, interpreted relative to the build context.
Example
dockerfile: docker/Dockerfile
ports
Publishes a container port on the host. The short syntax “8080:3000” reads host:container.
Example
ports:
- "8080:3000"
Without ports, containers on the same network can often reach each other directly.
expose
Documents a service's internal ports, without publishing them on the host.
Example
expose:
- "3000"
volumes (service)
Mounts storage in the container: a named volume or a host path.
Example
volumes:
- db_data:/var/lib/postgresql/data
volumes (root)
Declares the named volumes managed by the project, reused by the services.
Example
volumes:
db_data:
networks
Attaches services to one or more networks; service names are often used to communicate.
Example
networks:
- interne
environment
Variables passed to the container's process. They can change ports, the run mode or application behaviours.
Example
environment:
NODE_ENV: production
For credentials, prefer a secrets mechanism.
env_file
Loads environment variables from a text file of key=value pairs.
Example
env_file:
- .env.app
Avoid committing real secrets to Git.
depends_on
Controls dependencies and the order in which services are created. Does not guarantee that the dependent application is ready without a health condition.
Example
depends_on:
db:
condition: service_healthy
restart
Indicates the restart strategy applied to a container.
Example
restart: unless-stopped
healthcheck
A periodic health test of a service; lets Compose recognise the healthy state and condition dependencies on it.
Example
healthcheck:
test: ["CMD", "pg_isready", "-U", "app"]
interval: 10s
command
Replaces the image's default command at startup (often the CMD).
Example
command: ["node", "server.js"]
entrypoint
Replaces the entry executable defined in the image for a service.
Example
entrypoint: ["/app/start.sh"]
profiles
Lets you activate only certain optional services, such as debugging tools.
Example
profiles: ["debug"]
secrets
Declares sensitive data and distributes it to certain services as files.
Example
secrets:
- db_password
build.args
Passes parameters to the Dockerfile's ARGs during the build.
Example
build:
args:
APP_VERSION: "1.0"
deploy
Groups deployment options such as certain resource limits or replicas, depending on the run mode and its support.
Example
deploy:
resources:
limits:
memory: 512M
version (legacy)
A former compatibility field that has become obsolete. Modern Docker Compose is based on the current specification.
Example
Ne pas ajouter version: "3" dans un nouveau compose.yaml.
04 · Common mix-ups
These associations are worth understanding before changing an existing project.
RUN ≠ CMD
RUN works during docker build and leaves a result in the image. CMD defines what must start later, at docker run.
Example
RUN npm ci
CMD ["node", "server.js"]
CMD ≠ ENTRYPOINT
ENTRYPOINT chooses the main program. CMD can supply its default command or arguments; its values are more easily replaced at launch.
Example
ENTRYPOINT ["python"]
CMD ["app.py"]
ARG ≠ ENV
ARG concerns the build; ENV makes a value available in the image and the container. Neither should serve as a password vault.
Example
ARG VERSION=1.0
ENV MODE=production
EXPOSE ≠ ports
EXPOSE in a Dockerfile documents the internal port. ports in Compose sets up access through the host's port.
Example
EXPOSE 3000
ports: ["8080:3000"]
image ≠ build
image gives an image reference; build gives a recipe for making it. The two can appear together, with download and build rules worth knowing.
Example
image: monapp:dev
build: .
context ≠ WORKDIR
context determines the files accessible to the build from the host; WORKDIR is the current directory inside the image and the container.
Example
context: .
WORKDIR /app
depends_on ≠ ready
depends_on guarantees a creation sequence; to wait for a database to be available, combine a healthcheck with condition: service_healthy.
Example
depends_on:
db:
condition: service_healthy