3.1.1.2 Image Application Files

Image application files are the layers added on top of an image's base filesystem that contain the actual application — its source code or compiled binary, its own configuration files, and anything else specific to what the image is meant to run, as distinct from the underlying operating system layers it builds on.

Adding Application Files to an Image

The COPY and ADD instructions in a Dockerfile bring files from the build context into the image, producing a new layer containing exactly those files at the specified destination path.

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "server.js"]

The two COPY instructions here each produce their own layer, separating dependency manifests (which change less often) from the rest of the application source (which changes more often), to make better use of build caching.

Why Layer Ordering for Application Files Matters

Placing files that change frequently in later layers, and files that change rarely in earlier layers, means a rebuild after a small source code change only needs to redo the layers affected by that change, reusing everything earlier in the build from cache.

docker build -t myapp:1.1 .

If only application source changed and dependencies did not, this build reuses the cached dependency installation layer entirely, redoing only the layer containing the application's own files.

Application Configuration as Part of the Image

Some configuration that is genuinely fixed for a given build — rather than varying per environment — can be included directly as part of the application files layer, while environment-specific configuration is better supplied separately at run time.

COPY config/defaults.yaml /app/config/defaults.yaml

Inspecting What Application Files an Image Contains

The application-specific files within an image can be examined directly, which is useful for confirming a build actually included everything expected before deploying it.

docker run --rm myapp:1.0 ls -la /app

Why This Layer Distinction Matters

Separating application files conceptually (and often physically, in terms of Dockerfile layer ordering) from the underlying base filesystem clarifies exactly what is unique to a given application versus what is shared, generic infrastructure inherited from its base image.