Build

A Dockerfile has one build context, the directory you point docker build at. That’s enough for the vast majority of builds, but sometimes you need files from somewhere else: a base image, a separate git repository, a local directory outside the project root, or another service’s build output. additional_contexts lets you wire all of those into a single build. The basic shape Under build:, declare named contexts. Inside the Dockerfile, reference them with COPY --from=<name>: ...

By default, Compose pulls an image when it’s missing locally and uses the cached one otherwise. pull_policy lets you change that behavior per service. The policies services: web: image: nginx pull_policy: always Available values: missing (default when no build: is defined): pull only if the image is not present locally. Alias: if_not_present. Note: the latest tag is always pulled even with this policy. always: pull on every up, even if the local image is recent never: don’t pull, fail if the image is missing build: build the image, rebuilds even if it’s already present locally daily: check the registry if the last pull was more than 24 hours ago weekly: check the registry if the last pull was more than 7 days ago every_<duration>: check the registry if the last pull was older than the given duration. Units: w, d, h, m, s (or any combination, e.g. every_12h, every_30m, every_1d12h) When to use each always for development against a fast-moving tag: ...

Build args and environment variables both pass values to your containers, but they work at different times and serve different purposes. Mixing them up is a common source of confusion. Build args: build-time only Build args are available during docker build and are not present in the running container: services: app: build: context: . args: NODE_VERSION: "20" APP_VERSION: "2.1.0" In the Dockerfile, they’re consumed with ARG: ...

Multi-stage Dockerfiles let you define multiple build stages. With the target option in Compose, you can choose which stage to build — giving you different images from the same Dockerfile. A multi-stage Dockerfile # Stage 1: dependencies FROM node:20-slim AS deps WORKDIR /app COPY package*.json ./ RUN npm ci # Stage 2: development (with dev dependencies and tools) FROM deps AS dev RUN npm install --include=dev COPY . . CMD ["npm", "run", "dev"] # Stage 3: build FROM deps AS build COPY . . RUN npm run build # Stage 4: production (minimal) FROM node:20-slim AS production WORKDIR /app COPY --from=build /app/dist ./dist COPY --from=deps /app/node_modules ./node_modules CMD ["node", "dist/index.js"] Targeting stages in Compose Use target to pick which stage to build: ...

Speed up builds and reduce image size by managing build contexts effectively. Don’t send unnecessary files to the Docker daemon! Understanding build context The build context is what gets sent to Docker daemon: services: app: build: . # Current directory is the context # Everything in . gets sent to daemon! Check your context size: # See what's being sent docker build --no-cache . 2>&1 | grep "Sending build context" # Output: Sending build context to Docker daemon 458.2MB 😱 Custom build contexts Specify different contexts for different services: ...