Skip to content

Docker images, containers and registries

Docker packages an application together with its runtime, libraries and configuration defaults into an image, and runs that image as an isolated process called a container. This page explains the model behind that sentence: what an image is, what a container adds, how a container moves through its lifecycle, how images are named and versioned, and how they travel through registries such as Docker Hub.

The examples use an invented OrdersPortal application with an orders-api service. Docker Engine was not running in the environment used to write this page (the Docker CLI 29 client was installed but had no daemon), so docker commands and their output are not run here; they follow the docs.docker.com reference. To try them, install Docker Desktop or Docker Engine and run the commands in a terminal.

Topic What it answers
What Docker is The problem containers solve and the parts of the Docker platform.
Images and containers Read-only layers, the writable container layer, and why the difference matters.
Container lifecycle Creating, running, inspecting, stopping and removing containers.
Image names tags and digests How an image reference is built and which part to pin.
Registries and Docker Hub Pulling, logging in, pushing, pull limits and private registries.
Pushing images from CI Building and publishing images in a pipeline.
Cleaning up Reclaiming disk space safely.

The classic deployment failure is “it works on my machine”: the code is fine, but the server has a different runtime version, a missing system library or different configuration. Containers make the environment part of the deliverable. You build an image once, and the same image runs on a laptop, in CI and in production.

A container is not a virtual machine. It is an ordinary process on the host’s kernel, isolated with Linux namespaces (its own view of processes, network and file system) and limited with cgroups (CPU and memory). There is no guest operating system to boot, so containers start in milliseconds and use far less memory than VMs. The trade-off is that containers share the host kernel: a Linux container needs a Linux kernel, which Docker Desktop on macOS and Windows provides through a lightweight VM.

The Docker platform has a few parts you will meet constantly. Docker Engine is the daemon (dockerd) that builds images and runs containers, with the docker CLI as its client. Docker Desktop packages Engine, the CLI, Compose and BuildKit with a VM for macOS and Windows. BuildKit is the build backend behind docker build. Docker Compose runs multi-container applications from a YAML file. Docker Hub is the default public registry. Images follow the OCI (Open Container Initiative) specification, which is why an image built with Docker runs on Kubernetes, which uses containerd or CRI-O rather than Docker Engine.

Pitfalls:

  • Treating a container like a small server. Do not SSH in and patch it. Change the Dockerfile, build a new image and replace the container.
  • Assuming containers are a security boundary like VMs. They share the kernel. Run as a non-root user, drop capabilities and keep images minimal.

An image is a read-only template: an ordered stack of file system layers plus metadata (the default command, environment variables, exposed ports, the user to run as). Each instruction in a Dockerfile that changes files produces a layer. Layers are content-addressed and shared, so ten images built FROM the same base store that base once, and a push or pull transfers only the layers the other side is missing.

A container is a running (or stopped) instance of an image. Docker adds a thin writable layer on top of the image’s layers, plus runtime settings: the container’s name, its network, ports, mounted volumes and environment variables. Any file the process writes goes into that writable layer, using copy-on-write for files that came from the image. When the container is removed, its writable layer is deleted with it.

That gives a simple rule: images are immutable build artifacts; containers are disposable. Anything that must survive a container’s removal, such as database files or uploads, belongs in a volume (see Docker volumes and networking). Anything that differs between environments belongs in runtime configuration (see environment variables), not baked into the image.

Pitfalls:

  • Writing data into the container’s file system. It disappears on docker rm and slows down because of copy-on-write. Use volumes.
  • Building one image per environment. Build once, promote the same image through environments, and inject configuration at run time.

docker run creates a container from an image and starts it. The flags you use most: -d runs it in the background, --name gives it a stable name, -p host:container publishes a port, -e sets an environment variable, -v or --mount attaches storage, and --rm removes the container automatically when it exits.

Terminal window
# Not run here: requires a running Docker Engine
docker run -d --name orders-api -p 8080:8080 \
-e ASPNETCORE_ENVIRONMENT=Development \
registry.example.test/ordersportal/orders-api:2.4.1
docker ps # running containers (add -a for stopped ones)
docker logs -f orders-api # follow stdout and stderr
docker exec -it orders-api sh # open a shell inside the running container
docker inspect orders-api # full JSON: state, mounts, networks, env
docker stop orders-api # SIGTERM, then SIGKILL after the grace period (10 s by default)
docker start orders-api # start the same container again
docker rm orders-api # remove it (add -f to stop and remove)

A container lives as long as its main process (PID 1). When that process exits, the container stops, and its exit code tells you why: 0 for a clean exit, 137 when it was killed with SIGKILL (often an out-of-memory kill or the stop timeout), 143 for SIGTERM. Applications should handle SIGTERM and shut down cleanly within the grace period, which matters even more on Kubernetes, where every rollout stops containers.

A restart policy (--restart unless-stopped, on-failure, always) makes Engine restart a container when it exits or when the daemon starts. On a single host that is a basic form of self-healing; on a cluster, an orchestrator such as Kubernetes does this job.

Logs should go to stdout and stderr, not to files inside the container. Docker captures them through a logging driver, and every platform you deploy to later knows how to collect them from there.

Pitfalls:

  • A shell-form CMD that never forwards signals. With CMD node server.js in shell form, PID 1 is /bin/sh, which does not pass SIGTERM to Node.js; the container waits for the timeout and is killed. Use the exec form CMD ["node", "server.js"].
  • Using docker exec to fix things. The change is lost when the container is replaced. Use it to diagnose only.

A full image reference has up to four parts: registry/namespace/repository:tag@digest. For example, registry.example.test/ordersportal/orders-api:2.4.1. Missing parts get defaults: the registry defaults to Docker Hub (docker.io), official images live in the library namespace, and the tag defaults to latest. So docker pull nginx means docker.io/library/nginx:latest.

A tag is a mutable, human-friendly pointer. Publishers move tags: postgres:18 points to the newest 18.x patch release and changes over time, while postgres:18.1 changes less often. A digest (sha256:...) identifies the exact image content and never changes. Pin by digest when you need exact reproducibility (production deployments, base images in regulated builds), and use specific tags elsewhere.

Terminal window
# Not run here
docker tag orders-api:local registry.example.test/ordersportal/orders-api:2.4.1
docker tag orders-api:local registry.example.test/ordersportal/orders-api:2.4
docker image inspect --format '{{index .RepoDigests 0}}' registry.example.test/ordersportal/orders-api:2.4.1

A common tagging scheme publishes the full version (2.4.1), the minor line (2.4) and sometimes the Git commit SHA. Consumers who pin 2.4 get patch updates; consumers who pin 2.4.1 or a digest get none until they change the reference.

Pitfalls:

  • Deploying latest. You cannot tell which build is running, and a rollback has nothing to roll back to. Deploy immutable version tags or digests.
  • Re-pushing an existing version tag. Caches and nodes that already pulled the old content keep it. Treat published version tags as immutable; many registries can enforce this.

A registry stores and serves images. Docker Hub is the default public registry and hosts Docker Official Images (such as postgres, nginx and node), images from verified publishers, and community images. Cloud providers and code hosts offer private registries close to where you deploy: Amazon ECR, Azure Container Registry, Google Artifact Registry, GitHub Container Registry (ghcr.io) and the GitLab container registry. All speak the same OCI distribution API, so the commands are the same apart from the registry host.

Terminal window
# Not run here
docker login # Docker Hub
docker login registry.example.test # any other registry
docker push registry.example.test/ordersportal/orders-api:2.4.1
docker pull registry.example.test/ordersportal/orders-api:2.4.1

docker login stores credentials through a credential helper (the system keychain on Docker Desktop) or, without one, in ~/.docker/config.json. For automation, use access tokens rather than passwords: Docker Hub personal or organization access tokens, or the cloud provider’s short-lived login (aws ecr get-login-password, az acr login, gcloud auth configure-docker).

Docker Hub limits pulls. According to Docker’s documentation, unauthenticated pulls are limited to 100 per 6 hours per IPv4 address or IPv6 /64 subnet, authenticated Personal accounts to 200 per 6 hours, and paid plans are unlimited. Shared CI runners hit the unauthenticated limit quickly, so authenticate CI pulls or use a pull-through cache or mirror in your own registry.

Pitfalls:

  • Pulling base images anonymously in CI. Builds fail intermittently with rate-limit errors. Log in, or mirror base images.
  • Trusting any public image. Prefer Docker Official Images and verified publishers, pin versions, and scan images for vulnerabilities before use.

Production images should be built and pushed by a pipeline, not from laptops, so that every image is traceable to a commit. This GitHub Actions workflow builds the OrdersPortal API with Buildx and pushes it with the commit SHA as a tag. It is not run here; the action versions were checked against the actions’ repositories in November 2026.

.github/workflows/image.yml
name: Build and push orders-api
on:
push:
branches: [main]
jobs:
image:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v7
- uses: docker/setup-buildx-action@v4
- uses: docker/login-action@v4
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v7
with:
push: true
tags: ghcr.io/example-org/orders-api:${{ github.sha }}

The same steps work in GitLab CI/CD using the built-in CI_REGISTRY, CI_REGISTRY_USER and CI_REGISTRY_PASSWORD variables. Add a vulnerability scan and, for release builds, a version tag and a signature or attestation.

Pitfalls:

  • Long-lived registry passwords in CI variables. Prefer the CI system’s built-in token or OIDC-based short-lived credentials.
  • Tagging only by branch name. main is as mutable as latest. Always add an immutable tag such as the commit SHA.

Images, stopped containers, unused volumes and build cache accumulate quickly. Docker’s prune commands reclaim space; know what each removes before you run it.

Terminal window
# Not run here
docker system df # what is using space
docker container prune # remove stopped containers
docker image prune # remove dangling (untagged) images
docker image prune -a # also remove images not used by any container
docker volume prune # remove unused anonymous volumes only
docker volume prune -a # also remove unused named volumes: deletes data
docker builder prune # remove build cache

Since Docker Engine 23 (API 1.42), docker volume prune removes only anonymous volumes unless you add --all, which protects named volumes such as database data from routine cleanup.

Pitfalls:

  • docker system prune -a --volumes on a shared host. It removes every unused image and volume, including data another team’s stopped container needs.
  • Cleaning CI build cache on every run. Builds then start cold every time. Prune on a schedule instead.
You want to Use
Ship an application with its runtime An image built from a Dockerfile
Run it once to test docker run --rm
Keep it running on a single host docker run -d --restart unless-stopped, or Compose
Refer to an exact build A digest, or an immutable version tag
Share images inside a company A private registry close to your runtime
Run many containers across many hosts Kubernetes

What is the difference between an image and a container? An image is a read-only, layered template with metadata. A container is an instance of that image with a writable layer and runtime settings such as name, ports, network and mounts. Many containers can run from one image.

Why do containers start faster than virtual machines? A container is an isolated process on the host kernel, so nothing needs to boot. A VM boots a full guest operating system on virtualized hardware.

What is the difference between a tag and a digest? A tag is a mutable name that a publisher can move to new content. A digest is a hash of the image manifest and always identifies the same content.

Why does a container take ten seconds to stop and then exit with code 137? PID 1 did not handle SIGTERM, so Docker waited for the grace period and sent SIGKILL (128 + 9 = 137). A shell-form CMD is a common cause, because the shell does not forward signals. Use the exec form and handle SIGTERM in the application.

Senior scenario: OrdersPortal’s CI fails several times a day pulling base images, and production runs images nobody can trace to a commit. What do you change? Authenticate all CI pulls and add a pull-through cache or mirror for base images in the company registry, which removes the rate-limit failures and speeds builds. Build only in CI, tag every image with the commit SHA plus a release version, make version tags immutable in the registry, and deploy by digest. Add vulnerability scanning and provenance attestations to the pipeline so every running image can be traced to its source and build.