Core Docker Glossary and Reference Checklist

How to Use This Glossary and Checklist

This chapter is a quick-reference companion you can keep open while working. It focuses on terminology you will see in documentation, error messages, and team conversations, plus a practical checklist you can apply before shipping a containerized app. It avoids re-teaching topics you already covered (like how images/containers work, how to write Dockerfiles, how to run core commands, volumes, networks, and Compose). Instead, it clarifies the “extra” words that often cause confusion and provides a structured reference you can scan in minutes.

Reading tips

• Glossary entries give a plain-language definition, then a “why it matters” note.
• Reference checklists are actionable: you can copy them into a README or PR template.
• Examples are short and focused on interpretation and verification, not on reintroducing fundamentals.

Core Docker Glossary (Beginner-to-Intermediate)

Docker Engine

Meaning: The background service that builds and runs containers on your machine. It includes the container runtime and the API that tools talk to.

Why it matters: When something “Docker” fails, it’s often the Engine not running, lacking permissions, or using a different context than you expect.

Docker Desktop

Meaning: A packaged app for macOS/Windows (and some Linux setups) that includes Docker Engine plus a GUI, VM integration, and extra features.

Why it matters: Desktop can add layers (VM, file sharing, resource limits). Some performance and path issues are Desktop-specific.

Continue in our app.

You can listen to the audiobook with the screen off, receive a free certificate for this course, and also have access to 5,000 other free online courses.

Or continue reading below...

Download the app

Daemon (dockerd)

Meaning: The server process that manages images, containers, networks, and volumes.

Why it matters: Many errors are daemon-level (permissions, storage driver issues). If the daemon is down, client commands fail even if your CLI is installed.

Docker CLI (docker)

Meaning: The command-line client that sends requests to the Docker daemon.

Why it matters: The CLI can point to different environments (contexts). Two people can run the same command and affect different daemons.

Docker Context

Meaning: A named configuration that tells the Docker CLI which daemon to talk to (local, remote, cloud, etc.).

Why it matters: If you accidentally target a remote context, you may build/run containers somewhere else and wonder why nothing appears locally.

docker context ls
docker context show
docker context use default

Docker API

Meaning: The HTTP API exposed by the daemon that tools (including the CLI) use.

Why it matters: CI systems, IDEs, and orchestration tools rely on the API. Version mismatches can cause “client is newer than server” style errors.

OCI (Open Container Initiative)

Meaning: Standards for container image format and runtime behavior.

Why it matters: Explains why many tools can build/run “Docker images” even if they’re not Docker-branded. It also clarifies what is portable across runtimes.

Container Runtime (containerd, runc)

Meaning: Lower-level components used by Docker Engine to actually run containers.

Why it matters: Some errors mention these components. Knowing they exist helps you interpret logs and understand what “runtime” refers to.

Layer

Meaning: A filesystem change set that makes up an image. Images are stacks of layers.

Why it matters: Layer caching affects build speed and image size. When a layer changes, layers above it may rebuild.

Build Cache

Meaning: Stored results from previous builds used to speed up future builds.

Why it matters: If a build “doesn’t pick up changes,” you may be hitting cache unexpectedly. If builds are slow, cache might not be reused in CI.

BuildKit

Meaning: A modern build engine for Docker builds that improves performance, caching, and features (like secrets mounts during build).

Why it matters: Many advanced build features require BuildKit. Some build output and behavior differs from the legacy builder.

Tag

Meaning: A human-friendly label for an image reference, typically in the form name:tag (for example myapp:1.2.0).

Why it matters: Tags are mutable pointers. If you rely on latest, you might not get the same image tomorrow.

Digest

Meaning: A content-addressed identifier (hash) for an image, like @sha256:....

Why it matters: Digests are immutable. Pinning by digest improves reproducibility and supply-chain safety.

Repository (Image Repository)

Meaning: A collection of image versions under a name in a registry (for example myorg/myapp), with multiple tags/digests.

Why it matters: Helps you distinguish “repo name” from “tag.” People often say “push the image” when they mean “push a new tag to the repo.”

Registry

Meaning: A service that stores and serves container images.

Why it matters: Authentication, permissions, and rate limits are registry concerns, not Dockerfile concerns.

Base Image

Meaning: The starting image you build on top of.

Why it matters: Base image choice affects security updates, size, and compatibility. Many vulnerabilities come from the base image.

Distroless Image

Meaning: An image that contains only the application and its runtime dependencies, without a full OS userland (often no shell).

Why it matters: Smaller attack surface and size, but debugging is different because common tools aren’t present.

Alpine vs Debian/Ubuntu (Base Image Families)

Meaning: Common Linux base image families with different C libraries, package managers, and compatibility characteristics.

Why it matters: Some binaries expect glibc (common on Debian/Ubuntu) and may not work on musl-based Alpine without adjustments.

ENTRYPOINT vs CMD

Meaning: Image metadata that defines what runs by default. ENTRYPOINT is the “main executable,” CMD is the default arguments (or fallback command).

Why it matters: Misunderstanding this leads to containers that won’t accept arguments or override behavior cleanly.

Exec Form vs Shell Form

Meaning: Two ways to specify commands in Dockerfile instructions. Exec form is JSON array; shell form is a single string run through a shell.

Why it matters: Exec form handles signals and arguments more predictably; shell form can introduce quoting and signal-handling surprises.

PID 1

Meaning: The first process in a container. It has special signal-handling and zombie-reaping responsibilities.

Why it matters: If your app runs as PID 1 and doesn’t handle signals properly, docker stop may not shut down gracefully.

Signal (SIGTERM, SIGKILL)

Meaning: OS messages used to request process termination. Docker typically sends SIGTERM then SIGKILL after a timeout.

Why it matters: Graceful shutdown depends on handling SIGTERM. Databases and web servers often need time to flush/close.

Healthcheck

Meaning: A command defined for a container that reports whether the app is healthy.

Why it matters: Healthchecks help automation decide when a service is ready or should be restarted, rather than relying on “container is running.”

Restart Policy

Meaning: Rules for when Docker should restart a container (for example, on failure).

Why it matters: Prevents manual babysitting, but can also hide crash loops if you don’t monitor logs and exit codes.

Exit Code

Meaning: A numeric status returned when a process ends (0 usually means success; non-zero indicates failure).

Why it matters: CI/CD and restart policies often depend on exit codes. Knowing the code helps you diagnose why a container stopped.

Port Publishing vs Exposing

Meaning: “Expose” is documentation/metadata; “publish” maps a container port to a host port.

Why it matters: Confusion here leads to “my app works in the container but I can’t reach it from my browser.”

Environment Variable (Runtime Configuration)

Meaning: Key-value settings passed into a container at runtime.

Why it matters: Environment variables are convenient but can leak secrets if misused. They also affect reproducibility if not documented.

Secret (Build Secret vs Runtime Secret)

Meaning: Sensitive data (tokens, passwords). Build secrets are used during image build without baking them into layers; runtime secrets are provided at run time through secure mechanisms.

Why it matters: Accidentally embedding secrets into images is a common and serious mistake. Treat secrets as separate from images.

Bind Mount vs Named Volume

Meaning: Two ways to persist data: bind mounts map a host path; named volumes are managed by Docker.

Why it matters: Bind mounts are great for local dev; named volumes are often safer and more portable for long-lived data.

Storage Driver

Meaning: The mechanism Docker uses to manage layered filesystems (for example overlay-based drivers).

Why it matters: Performance and disk usage issues can be storage-driver related. Some errors mention “overlay” or “snapshotter.”

Prune / Garbage Collection

Meaning: Removing unused images, containers, networks, and build cache.

Why it matters: Docker can consume significant disk space over time. Pruning is maintenance, but must be done carefully to avoid deleting needed artifacts.

Multi-Architecture (multi-arch) Image

Meaning: A single image reference that supports multiple CPU architectures (for example amd64 and arm64) via a manifest list.

Why it matters: Essential when your team uses different hardware (Intel/AMD laptops vs Apple Silicon) or when deploying to mixed infrastructure.

Manifest / Manifest List

Meaning: Metadata that describes what image layers exist and, for manifest lists, which image variant matches which platform.

Why it matters: Explains why pulling the “same tag” on different machines can yield different binaries.

Rootless Docker

Meaning: Running the Docker daemon and containers without root privileges.

Why it matters: Improves security posture, but can introduce limitations around networking and filesystem permissions.

User Namespace Remapping

Meaning: A security feature mapping container user IDs to different host user IDs.

Why it matters: Helps reduce risk if a container escapes, but can complicate file ownership on mounted paths.

Capabilities

Meaning: Fine-grained Linux privileges that can be added or removed from containers.

Why it matters: Many apps do not need full privileges. Dropping capabilities reduces the blast radius of a compromise.

Seccomp Profile

Meaning: A filter restricting which system calls a container can make.

Why it matters: Another layer of defense. Some workloads need relaxed profiles; most should keep defaults.

Read-only Root Filesystem

Meaning: Running a container with its root filesystem mounted read-only.

Why it matters: Prevents many persistence techniques used by attackers and forces you to explicitly define writable paths.

Resource Limits (CPU/Memory)

Meaning: Constraints on how much CPU and RAM a container can use.

Why it matters: Prevents one container from starving others and makes behavior more predictable under load.

Logging Driver

Meaning: The mechanism Docker uses to collect and store container logs (for example JSON files, syslog, or centralized logging backends).

Why it matters: Determines where logs go, how they rotate, and how you should collect them in production.

Image Scanning

Meaning: Checking images for known vulnerabilities and risky configurations.

Why it matters: Helps catch outdated libraries and insecure defaults before deployment.

SBOM (Software Bill of Materials)

Meaning: A machine-readable inventory of components included in your image (libraries, packages, versions).

Why it matters: Improves auditing and incident response: you can quickly answer “are we affected by this CVE?”

Provenance / Attestation

Meaning: Metadata about how an image was built (source, build steps, builder identity), often used in supply-chain security.

Why it matters: Helps establish trust that an image came from your pipeline and wasn’t tampered with.

Image Signing

Meaning: Cryptographically signing images so consumers can verify publisher identity and integrity.

Why it matters: Prevents “pull and run whatever is in the registry” from becoming a supply-chain risk.

Reference Checklist: Before You Share an Image

1) Naming, versioning, and immutability

• Use a meaningful tag (for example 1.4.2 or 2026-01-14) rather than relying on latest.
• Record the digest of the released image for traceability.
• Document supported platforms (amd64/arm64) if you publish multi-arch.

2) Security basics

• Run as a non-root user unless there is a clear reason not to.
• Do not bake secrets into the image (no API keys in layers, no private tokens in build output).
• Prefer minimal base images when feasible, and keep them updated.
• Consider read-only filesystem and explicitly mount writable paths if your app supports it.
• Drop unnecessary Linux capabilities for the workload.

3) Operational readiness

• Define a healthcheck that reflects real readiness (not just “process exists”).
• Ensure graceful shutdown (SIGTERM handling) so deployments and restarts are safe.
• Set log expectations: write logs to stdout/stderr and avoid writing logs to random files unless you manage rotation.
• Document required environment variables and defaults.

4) Size and performance

• Remove build-only artifacts from the final runtime image (use multi-stage builds where appropriate).
• Avoid unnecessary packages that increase size and vulnerability surface.
• Verify cold start time is acceptable for your environment.

Reference Checklist: Before You Run in Production (or “Production-like”)

1) Configuration and secrets handling

• List all runtime configuration inputs: environment variables, mounted config files, command arguments.
• Choose a secrets strategy appropriate for your environment (avoid plaintext in repos; avoid leaking secrets via docker inspect when possible).
• Confirm default configuration is safe (no debug mode, no open admin endpoints).

2) Networking and exposure

• Publish only necessary ports to the host.
• Bind to the correct interface when publishing (avoid exposing to the world unintentionally).
• Confirm service-to-service communication paths are intentional (no accidental access to internal-only services).

3) Resource management

• Set memory limits to prevent host exhaustion.
• Set CPU limits or reservations if you need predictable performance.
• Monitor for OOM kills and adjust limits based on real usage.

4) Filesystem and persistence

• Identify what must persist (uploads, database files, caches) and ensure it is stored in the right place.
• Verify permissions for mounted paths when running as non-root.
• Ensure backups exist for persistent data and that restore is tested.

5) Observability

• Logs: confirm logs are accessible where your team expects them.
• Metrics: if applicable, confirm metrics endpoints are reachable only by intended systems.
• Tracing: if used, confirm trace context is propagated and sampling is configured.

Step-by-Step: Quick Self-Audit of an Image (Local)

This short procedure helps you validate an image you built or pulled, focusing on what you can verify quickly without redoing earlier chapters.

Step 1: Identify what you are about to run

docker image ls

• Confirm the repository and tag are what you expect.
• If you are preparing a release, prefer referencing the digest as well.

Step 2: Inspect metadata (entrypoint, command, user, exposed ports)

docker image inspect YOUR_IMAGE:TAG

Look for these fields in the output:

• Config.Entrypoint and Config.Cmd: confirm the default startup behavior.
• Config.User: confirm it is not empty (often means root) unless intentionally required.
• Config.ExposedPorts: confirm which ports the image declares.
• RepoDigests: capture the digest for traceability.

Step 3: Check which architecture you pulled/built

docker image inspect --format '{{.Os}}/{{.Architecture}}' YOUR_IMAGE:TAG

If teammates use different machines, confirm you are not accidentally building only for your local architecture.

Step 4: Run a minimal smoke test and capture exit code

docker run --rm YOUR_IMAGE:TAG
echo $?

• If the container exits immediately with a non-zero code, treat it as a failing startup.
• If it runs a server and blocks, stop it and confirm it shuts down gracefully.

Step 5: Validate health behavior (if a healthcheck exists)

docker run -d --name tempcheck YOUR_IMAGE:TAG
docker inspect --format '{{json .State.Health}}' tempcheck
docker rm -f tempcheck

Confirm the health status transitions to healthy within a reasonable time and that failures provide useful output.

Step-by-Step: Quick Container Runtime Safety Checks

Step 1: Confirm the container is not running as root (when possible)

docker run --rm YOUR_IMAGE:TAG id

Interpretation:

• If output shows uid=0(root), the container runs as root by default.
• If it shows a non-zero UID, you have a safer default posture.

Step 2: Confirm signal handling (graceful stop)

docker run -d --name sigtest YOUR_IMAGE:TAG
docker stop -t 10 sigtest
docker ps -a --filter name=sigtest
docker rm sigtest

Interpretation:

• If the container stops within the timeout, it likely handles SIGTERM properly.
• If it frequently needs SIGKILL (after timeout), consider adjusting the app or entrypoint to forward signals correctly.

Step 3: Confirm logs go to stdout/stderr

docker run -d --name logtest YOUR_IMAGE:TAG
docker logs --tail 50 logtest
docker rm -f logtest

Interpretation:

• You should see application logs via docker logs.
• If logs are empty but the app is active, it may be logging only to files inside the container, which complicates operations.

Common “Docker Words” You’ll See in Errors (Translation Guide)

“permission denied” (socket or filesystem)

Usually means: Your user cannot access the Docker daemon socket, or a mounted path has ownership/permission mismatch.

What to check: Whether Docker Engine is reachable, whether your user is allowed to talk to it, and whether mounted directories are writable by the container user.

“no space left on device”

Usually means: Docker’s storage (images, layers, build cache, volumes) has filled the disk, not necessarily your project folder.

What to check: Disk usage and whether old images/containers/build cache should be cleaned up.

“exec format error”

Usually means: Architecture mismatch (for example, running an amd64 image on arm64 without emulation support).

What to check: The image architecture and whether a multi-arch image is available.

“address already in use”

Usually means: You tried to publish a host port that another process/container is already using.

What to check: Which service is bound to that host port and whether you should choose a different host port.

“connection refused” (between services)

Usually means: The target service is not listening on the expected address/port, is not ready yet, or a firewall/network rule blocks it.

What to check: Service readiness, correct hostnames, correct ports, and whether the service binds to the right interface.

“context deadline exceeded” / “i/o timeout” (pull/push)

Usually means: Network issues, DNS problems, proxy misconfiguration, or registry rate limits.

What to check: Connectivity to the registry, proxy settings, and whether authentication is required.

Mini Reference: What to Document in a Container README

When you share a container with teammates, a short README prevents repeated questions. Include:

• Image reference: repository, tag, and (for releases) digest.
• Supported platforms: amd64/arm64.
• Required configuration: environment variables, config files, command arguments.
• Ports: which container ports exist and which host ports should be published (if any).
• Persistence: which paths must be writable and what should be stored in volumes.
• Healthcheck behavior: what “healthy” means and typical time to become ready.
• Operational notes: graceful shutdown expectations, log location (stdout/stderr), resource recommendations.
• Security notes: default user, any required privileges, and how secrets must be provided.