Docker & Docker Compose — The course

Guide 03 / 3

Dockerfile & compose.yaml

Understand each instruction and its consequences on the build or at run time.

Expected outcome :

Explain the Dockerfile → image → container cycle and configure Compose services.

Reading
0%

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.

Dockerfile → docker build → image

compose.yaml

A YAML declaration of services, volumes and networks. Compose interprets this configuration to create and run the containers.

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.

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.

FROM python:3.13-slim
Remember :

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.

RUN pip install --no-cache-dir -r requirements.txt
Remember :

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.

CMD ["python", "app.py"]
Remember :

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.

ENTRYPOINT ["python", "app.py"]
Remember :

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.

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.

ADD archive.tar.gz /opt/app/
Remember :

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.

WORKDIR /app

ENV

Defines a variable available during the following instructions and in containers based on the image.

ENV APP_MODE=production
Remember :

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.

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.

EXPOSE 3000
Remember :

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.

USER app

HEALTHCHECK

Defines a periodic test that indicates whether the application really works, beyond the mere presence of its process.

HEALTHCHECK CMD wget -q -O - http://localhost:3000/health || exit 1
Remember :

The program used for the test must be present in the image.

LABEL

Adds metadata as key=value pairs, useful for traceability.

LABEL org.opencontainers.image.title="Mon API"

VOLUME

Declares a mount point intended for data. In practice, persistence is often configured in Docker Compose.

VOLUME /data

SHELL

Changes the interpreter program used by shell-form instructions.

SHELL ["/bin/sh", "-c"]

ONBUILD

Registers an instruction triggered when this image later serves as the base image of another Dockerfile.

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.

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.

name: demo-web

services

The root section containing all the application's services. A service describes the image and configuration of its containers.

services:
  web:

image

The image to use: either pulled from a registry, or tied to the build result depending on the configuration.

image: nginx:alpine

build

Tells Compose how to make an image. Can be a short path or a detailed object.

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.

context: .

dockerfile

The path of an alternative build file, interpreted relative to the build context.

dockerfile: docker/Dockerfile

ports

Publishes a container port on the host. The short syntax “8080:3000” reads host:container.

ports:
  - "8080:3000"
Remember :

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.

expose:
  - "3000"

volumes (service)

Mounts storage in the container: a named volume or a host path.

volumes:
  - db_data:/var/lib/postgresql/data

volumes (root)

Declares the named volumes managed by the project, reused by the services.

volumes:
  db_data:

networks

Attaches services to one or more networks; service names are often used to communicate.

networks:
  - interne

environment

Variables passed to the container's process. They can change ports, the run mode or application behaviours.

environment:
  NODE_ENV: production
Remember :

For credentials, prefer a secrets mechanism.

env_file

Loads environment variables from a text file of key=value pairs.

env_file:
  - .env.app
Remember :

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.

depends_on:
  db:
    condition: service_healthy

restart

Indicates the restart strategy applied to a container.

restart: unless-stopped

healthcheck

A periodic health test of a service; lets Compose recognise the healthy state and condition dependencies on it.

healthcheck:
  test: ["CMD", "pg_isready", "-U", "app"]
  interval: 10s

command

Replaces the image's default command at startup (often the CMD).

command: ["node", "server.js"]

entrypoint

Replaces the entry executable defined in the image for a service.

entrypoint: ["/app/start.sh"]

profiles

Lets you activate only certain optional services, such as debugging tools.

profiles: ["debug"]

secrets

Declares sensitive data and distributes it to certain services as files.

secrets:
  - db_password

build.args

Passes parameters to the Dockerfile's ARGs during the build.

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.

deploy:
  resources:
    limits:
      memory: 512M

version (legacy)

A former compatibility field that has become obsolete. Modern Docker Compose is based on the current specification.

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.

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.

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.

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.

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.

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.

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.

depends_on:
  db:
    condition: service_healthy