Introduction to Docker Images

A Docker image is an immutable package containing an application’s filesystem and the configuration needed to start it.

When you run an image, Docker creates a container with a writable layer on top. Changes made inside that container do not modify the original image.

What is inside a Docker image?

An image contains:

• Filesystem layers with the app, runtime, libraries, and system files
• Configuration such as the default command, working directory, user, and environment variables
• Metadata describing the image

Image layers are content-addressed and can be shared between images. If two images use the same base layers, Docker only needs to store those layers once.

How do you build an image?

You normally describe an image with a Dockerfile.

Here is a small Node.js example:

FROM node:22-bookworm-slim

WORKDIR /app

COPY package*.json ./
RUN npm ci --omit=dev

COPY . .

USER node

CMD ["node", "server.js"]

Build it from the directory containing the Dockerfile:

docker build -t notes-api:1.0 .

The final dot is the build context. Docker can access files in that directory when processing COPY instructions.

Add a .dockerignore file so the build context does not include files such as .git, local dependencies, logs, or secrets.

List the images stored locally:

docker image ls

Then start a container from the image:

docker run --name notes-api -p 3000:3000 notes-api:1.0

What are tags and digests?

In notes-api:1.0, 1.0 is a tag. Tags are readable names, but they are mutable: a registry can make the same tag point to a different image later.

A digest identifies image content:

node@sha256:...

Use a digest when you need a build to select the exact same base image every time. Remember that a pinned digest does not receive security fixes automatically. Update it deliberately and rebuild regularly.

A tag can also refer to a multi-platform image. Docker chooses the matching image for the host’s operating system and CPU architecture from its manifest.

Where are images stored?

Images can stay in the local image store or be pushed to a registry.

Docker Hub hosts public and private images. The official Node.js image, for example, provides several Node.js versions and base operating systems.

Other services and private deployments can provide compatible registries too.

Pull an image with:

docker pull node:22-bookworm-slim

How do you choose and build safer images?

Start with a trusted base image that contains only what the application needs. Smaller images download faster and usually contain fewer packages that need security updates.

Good defaults include:

• Use a specific version tag instead of latest
• Rebuild often to include current base-image and dependency fixes
• Use multi-stage builds when build tools are not needed at runtime
• Run the final application as a non-root user
• Never copy secrets, credentials, or a local .env file into the image
• Scan images and their dependencies before deployment
• Build and test images in CI

Order Dockerfile instructions so stable dependency-installation layers come before frequently changing source code. This lets Docker reuse its build cache.

Picking a base image affects how big your final image gets — I built a free Docker base image size comparison that shows common choices side by side.

The official Docker guide has more detail on image concepts and Dockerfile best practices.

Related posts about docker: