3.1.1.4 Image Metadata
A focused guide to Image Metadata, connecting core concepts with practical Docker and container operations.
Image metadata is the configuration information stored alongside an image's filesystem layers, describing how a container should behave by default when started from it — its default command, exposed ports, environment variables, working directory, and other runtime defaults.
What Metadata Describes
Unlike layers, which define filesystem content, metadata defines behavior: what process to run, what ports the application expects to use, what environment variables should be set unless overridden, and which user the container's process should run as.
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
EXPOSE 3000
USER node
CMD ["node", "server.js"]
Each of these instructions contributes to the image's metadata rather than adding filesystem content directly.
Inspecting an Image's Metadata
The complete metadata for any image can be inspected directly, which is useful for understanding exactly what defaults a container will have before actually starting one.
docker inspect myapp:1.0 --format '{{json .Config}}'
This returns the full configuration object, including default environment variables, exposed ports, working directory, and the default command.
Metadata Can Be Overridden at Run Time
Image metadata defines defaults, not fixed behavior — most of it can be overridden when a container is actually started, without needing to rebuild the image.
docker run -e NODE_ENV=development -p 8080:3000 myapp:1.0
This overrides the default environment variable and adds an explicit port mapping, while the image's metadata itself remains unchanged.
EXPOSE Is Documentation, Not Enforcement
The EXPOSE instruction records which ports the application expects to use as metadata, but it does not, on its own, make those ports reachable from outside the container — actual port publishing still requires an explicit mapping at run time.
docker run -p 3000:3000 myapp:1.0
Why Image Metadata Matters
Metadata is what makes an image self-describing: anyone receiving the image can determine how it is meant to be run without needing separate documentation, since the expected ports, environment, and startup command are recorded directly as part of the image itself.