Inspecting an Image

An image is a dependency you are about to trust with your application, and it can be read like one. docker image inspect, docker history, and a glance at its layers and size tell you what base it's built on, what command it runs, what ports it exposes, and — the part most people skip — whether anything sensitive was baked into its history. Reading an image before you run it is a basic supply-chain habit, no different from skimming a library's source before you import it.

Driftwood depends on postgres:16 and nginx:1.27-alpine, and this topic reads both the way you'd read a third-party package: what they execute by default, what they expose, what they declare as volumes, and whether their build hid anything you'd rather know about.

docker image inspect

docker image inspect dumps the image config as JSON: the default CMD and ENTRYPOINT, the ENV variables, exposed ports, the working directory, declared volumes, labels, and the architecture. Reading it tells you what a container will do before you start one — what process runs, what environment it inherits, what it expects to listen on.

$ docker image inspect postgres:16 --format '{{json .Config}}' | jq
{
  "Entrypoint": ["docker-entrypoint.sh"],
  "Cmd": ["postgres"],
  "Env": ["PG_MAJOR=16", "PGDATA=/var/lib/postgresql/data", "..."],
  "ExposedPorts": { "5432/tcp": {} },
  "Volumes": { "/var/lib/postgresql/data": {} },
  "WorkingDir": "",
  "Labels": null
}

For postgres:16 the readout is concrete: it runs docker-entrypoint.sh postgres, exposes 5432/tcp, and declares /var/lib/postgresql/data as a volume. That last line matters — it means an anonymous volume appears automatically unless you mount your own, which is exactly the kind of surprise you want to know about before wiring the image into Compose.

docker history

docker history lists each layer with the Dockerfile instruction that created it and its size. It is how the image was built, read backwards — and it is where secrets hide. A value passed via ARG or ENV, or a file added in one layer and "deleted" in a later one, shows up in the history even though it isn't visible in a running container.

$ docker history nginx:1.27-alpine
IMAGE          CREATED       CREATED BY                                      SIZE
b4e3f1a2c9d0   2 weeks ago   CMD ["nginx" "-g" "daemon off;"]                0B
<missing>      2 weeks ago   EXPOSE 80                                       0B
<missing>      2 weeks ago   RUN /bin/sh -c set -x && apk add --no-cache …   24.1MB
<missing>      2 weeks ago   COPY docker-entrypoint.sh /                     2.6KB
<missing>      3 weeks ago   /bin/sh -c #(nop) ADD file:… in /               7.4MB

The per-layer instructions read like a condensed Dockerfile. If a build had done RUN echo $SECRET > /tmp/key && … && rm /tmp/key, the key's bytes would still be in that layer regardless of the later rm — which is precisely why build secrets need BuildKit's --secret mount rather than an ARG, a point the Dockerfile chapter develops.

Reading Size and Layers

Per-layer sizes show where the weight actually is. An image's total is just the sum of its layers, so a single 400 MB layer is usually one uncleaned package cache or one fat COPY — and docker history names the exact instruction that produced it. That turns image-shrinking from guesswork into targeting: you fix the instruction that costs the bytes, not whichever one you noticed first.

This is the diagnostic that directs the size work in the Dockerfile chapter. Before optimizing anything, you read the history, find the heaviest layer, and look at the instruction above it — the bloat almost always has a single, nameable cause.

Labels and Provenance

Well-built images carry OCI labels — source repository, revision, build date — recorded in the config. Their presence is a quick signal of how carefully an image was produced: an image that declares where its source lives and which commit built it is one you can trace, while one with Labels: null tells you nothing about its origin. It's a thirty-second provenance check before you depend on something.

Inspecting Driftwood's Dependencies

Reading postgres:16 and nginx:1.27-alpine this way surfaces exactly what you need before composing them. Postgres runs postgres under its entrypoint, listens on 5432, and declares a data volume; nginx runs nginx -g 'daemon off;', exposes 80, and copies in an entrypoint script. Those are the defaults, ports, and volumes you'll wire into Compose later — and knowing them now means no surprises about anonymous volumes or unreachable services then.

The habit generalizes past these two. Any image you're about to run, you inspect first: its entrypoint so you know what executes, its history so you know what's hidden, its exposed ports and volumes so you know how it'll behave. It costs a minute and prevents a class of "why is this doing that" debugging later.