Lesson 06 intermediate

Docker Images

Pull, inspect, tag, push and clean up images, choose a good base image, and build for both amd64 and arm64.

Images are the deliverable of everything you do with Docker. This lesson covers the day-to-day image commands, how to publish to a registry, how to keep disks from filling up, and how to pick a base image that is small and safe.

Pull and list images

docker pull downloads an image without running it. Pin a version tag so you know what you get:

$ docker pull postgres:17-alpine
17-alpine: Pulling from library/postgres
Digest: sha256:7c688148e5e156d0e86df7ba8ae5a05a2386aaec1e2ad8e6d11bdf10504b1fb7
Status: Downloaded newer image for postgres:17-alpine
docker.io/library/postgres:17-alpine
$ docker images
REPOSITORY   TAG         IMAGE ID       CREATED        SIZE
postgres     17-alpine   2f1c7a9b4e3d   9 days ago     278MB
nginx        1.27        a6b2c9e1f0d4   3 weeks ago    192MB
hello-node   1.0         c4e8f1a2b7d9   2 hours ago    160MB

Inspect what is inside

docker image inspect prints the full metadata as JSON. Use --format to pick fields, such as the default command, environment and exposed ports:

$ docker image inspect --format '{{.Config.Cmd}} {{.Config.ExposedPorts}}' nginx:1.27
[nginx -g daemon off;] map[80/tcp:{}]
$ docker image inspect --format '{{.Os}}/{{.Architecture}}' nginx:1.27
linux/amd64

To look around inside an image without starting its normal process, override the command with a shell:

$ docker run --rm -it nginx:1.27 sh -c 'ls /usr/share/nginx/html'
50x.html  index.html

Tag and push to a registry

A tag is a pointer, and one image can have many. To publish, tag the image with the registry and repository name, log in, then push:

$ docker tag hello-node:1.0 ghcr.io/jeff/hello-node:1.0
$ echo "$GHCR_TOKEN" | docker login ghcr.io -u jeff --password-stdin
Login Succeeded
$ docker push ghcr.io/jeff/hello-node:1.0
The push refers to repository [ghcr.io/jeff/hello-node]
5f70bf18a086: Pushed
1.0: digest: sha256:9b2e64f0c1d7a3e85b4f6c2d1a0e9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f size: 1365

Tip: --password-stdin keeps the token out of your shell history and process list. In CI, use the registry’s short-lived tokens instead of personal passwords.

Most teams push two tags per build: an immutable one (the version or git SHA) for deploys, and a moving one like main for convenience.

Choose a base image

The FROM line decides most of your image’s size and its security surface:

Base imageSize (approx.)Good forWatch out for
ubuntu:24.04, debian:1275–120 MBFamiliar tools, easy debuggingLarger, more packages to patch
*-slim variants30–80 MBMost apps: Debian with the extras removedMissing tools like curl until you add them
alpine5–10 MBTiny images, fast pullsUses musl instead of glibc; some binaries misbehave
gcr.io/distroless/*2–30 MBProduction runtimes with no shellNo shell to debug with
scratch0 MBStatic binaries (Go, Rust)Nothing at all: add certificates yourself

Start with the official -slim image for your language, and move to distroless once your build is stable.

Build for amd64 and arm64

Laptops with Apple silicon and ARM servers (such as AWS Graviton or Oracle Ampere) use arm64, while most other machines use amd64. Buildx builds both and pushes one multi-platform tag:

$ docker buildx create --use --name multi
multi
$ docker buildx build --platform linux/amd64,linux/arm64 \
  -t ghcr.io/jeff/hello-node:1.1 --push .
 => [linux/amd64 1/3] FROM docker.io/library/node:22-alpine
 => [linux/arm64 1/3] FROM docker.io/library/node:22-alpine
 => pushing manifest for ghcr.io/jeff/hello-node:1.1

Every machine pulling hello-node:1.1 now gets the variant for its own CPU.

Clean up disk space

Images pile up quickly on build machines. See what Docker uses, then prune:

$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          23        4         6.42GB    5.1GB (79%)
Containers      5         2         12.3MB    8.1MB (65%)
Local Volumes   3         2         1.2GB     240MB (20%)
Build Cache     41        0         2.3GB     2.3GB
$ docker image prune
Total reclaimed space: 1.08GB
$ docker image prune -a --filter "until=168h"

docker image prune only removes dangling images (no tag). With -a it removes every image not used by a container; the filter keeps anything newer than a week.

Exercise

An image built on an Apple Silicon Mac fails on the production amd64 server with “exec format error”. What fixes it?

  1. Making the entrypoint executable with chmod +x
  2. Switching the base image to Alpine
  3. Building for the server’s platform, e.g. docker buildx build --platform linux/amd64,linux/arm64
  4. Running docker system prune on the server
Show answer

Answer: C. The Mac produced arm64 binaries that an amd64 CPU cannot execute. Buildx can build one multi-platform image, and each server pulls the variant that matches its CPU.

Key takeaways

  • Pin image tags, and use digests when you need exact reproducibility.
  • docker image inspect --format answers “what does this image run?” without starting it.
  • Tag with the registry name, log in with --password-stdin, then docker push.
  • Pick -slim or distroless bases, build multi-platform with Buildx, and prune regularly.

FAQ

Why does my image work on my Mac but fail on the server with “exec format error”?

It was built for arm64 (Apple silicon) and the server is amd64, or the other way around. Build with --platform linux/amd64, or build a multi-platform image with Buildx.

How do I scan an image for vulnerabilities?

Run docker scout cves <image>, or use an open source scanner such as Trivy (trivy image <image>). Add the scan to CI so vulnerable images never reach production.

Can I delete an image that a container is using?

Not while a container (even a stopped one) references it. Remove the container first, or use docker rmi -f, which only removes the tag and leaves the data in use.

↑ ↓ navigate Enter open Esc close