Originally published on docker.learnio.dev — part of the Docker fundamentals course. View this lesson on the original site.

The local loop: build, name, inspect

You can read Docker theory for a long time and still feel lost when CI fails. The useful floor skill is mechanical: turn a Dockerfile into a tagged artifact, run it once, and read what the engine stored.

The questions you should answer without guessing:

  • what image did I just build
  • what tags point at it
  • what metadata is baked in
  • what layers produced it

GitHub example (clone and run)

Use the ready-made project instead of typing the Dockerfile from scratch:

Academy repo: 2-images-layers/img-min-build-tag-inspect

git clone https://github.com/stuarttodd-dev/halfshellstudios-academy.git
cd halfshellstudios-academy/docker-fundamentals/2-images-layers/img-min-build-tag-inspect
docker build -t img-min:1 .
docker run --rm img-min:1

The folder should contain at minimum a Dockerfile and a short README.md with the build, tag, inspect, and history commands from this lesson.

A tiny Dockerfile (if you are not using the repo)

mkdir -p /tmp/img-min && cd /tmp/img-min
cat > Dockerfile <<'EOF'
FROM alpine:3.20
RUN echo "hello from image" > /hello.txt
CMD ["cat", "/hello.txt"]
EOF

Build and run

-t applies a human-friendly tag. The trailing . is the build context (the directory the builder may read):

{
  "ariaLabel": "docker build -t img-min:1 with build context dot",
  "segments": [
    { "text": "docker", "bottomLabel": { "text": "CLI" } },
    { "text": "build", "topLabel": { "text": "Command", "variant": "command" }, "highlight": "command" },
    { "text": "-t", "bottomLabel": { "text": "Tag flag" } },
    { "text": "img-min:1", "topLabel": { "text": "Tag", "variant": "tag" }, "highlight": "tag" },
    { "text": ".", "bottomLabel": { "text": "Build context" } }
  ]
}

docker build -t img-min:1 .
docker image ls img-min
docker run --rm img-min:1

You should see hello from image on stdout and img-min:1 in docker image ls.

Add a second tag (no rebuild)

Tags are labels on one image ID:

{
  "ariaLabel": "docker image tag adds a second name to the same image ID",
  "segments": [
    { "text": "docker", "bottomLabel": { "text": "CLI" } },
    { "text": "image", "bottomLabel": { "text": "Object" } },
    { "text": "tag", "topLabel": { "text": "Command", "variant": "command" }, "highlight": "command" },
    { "text": "img-min:1", "bottomLabel": { "text": "Existing tag" } },
    { "text": "img-min:latest", "topLabel": { "text": "New tag", "variant": "tag" }, "highlight": "tag" }
  ]
}

docker image tag img-min:1 img-min:latest
docker image ls img-min

Both rows should share the same IMAGE ID. You did not build twice.

Inspect metadata and layers

docker image inspect --format 'tags={{.RepoTags}} arch={{.Architecture}}' img-min:1
docker image inspect --format 'layer count={{len .RootFS.Layers}}' img-min:1
docker history --no-trunc img-min:1
  • docker image inspect shows config, architecture, env, and the layer list
  • docker history shows which Dockerfile instruction created each layer (newest entry at the top)

Prepare a registry-shaped name locally

Retagging for a registry hostname does not push anything yet:

docker image tag img-min:1 ghcr.io/your-org/img-min:1
docker image ls ghcr.io/your-org/img-min

Same image ID, extra name. Push comes later when you authenticate to the registry.

Try it yourself

Work through the full loop in order. Stop when each step matches the expected output.

  1. Clone the GitHub example or create the Dockerfile under /tmp/img-min.
  2. Build with docker build -t img-min:1 .
  3. Confirm docker image ls shows the new tag and note the IMAGE ID.
  4. Run docker run --rm img-min:1 and confirm the hello line prints.
  5. Tag again: docker image tag img-min:1 img-min:backup and verify all three names (:1, :latest if you added it, :backup) share one ID.
  6. Run docker history --no-trunc img-min:1 and identify which line came from RUN echo ....
  7. Change the Dockerfile message, rebuild as img-min:2, and confirm :1 and :2 are different IDs.

Success looks like: you can name an image, prove it runs, explain why two tags can reference one build, and spot which history line added /hello.txt.

From Docker fundamentals — Images, layers, tags, and everyday commands