Docker Images, Layers, Registries & S3 — Explained with a Concrete Example

Imagine you’re building a Python web app and want to ship it as a Docker image.

The starting point: your Dockerfile

FROM python:3.11           # Step 1
RUN pip install flask      # Step 2
COPY app.py /app/          # Step 3
CMD ["python", "/app/app.py"]

When you run docker build, Docker doesn’t make one giant blob. It makes layers.

Term 1: Layer

A layer is a snapshot of filesystem changes from one Dockerfile step. For example:

• Layer A = the entire python:3.11 filesystem (~900 MB)
• Layer B = the files Flask added (~5 MB)
• Layer C = just your app.py (~2 KB)

Each layer is stored separately on disk. Docker stacks these layers on top of each other to form the final container filesystem.

Term 2: Checksum (SHA256 digest)

Every layer gets a fingerprint called a checksum (or digest), for example:

sha256:9f2c1b3e8a...

This checksum is computed from the layer’s contents. That means:

• Same contents → same checksum
• Different contents → different checksum

Docker uses this for cache reuse, deduplication, and avoiding unnecessary uploads/downloads. If Docker already has a layer with digest sha256:9f2c1b3e8a..., it knows it does not need to download or upload it again.

Term 3: Manifest

A manifest is a tiny JSON file describing the image.

{
  "layers": [
    { "digest": "sha256:9f2c1b3e8a..." },
    { "digest": "sha256:4d8e2a1f7c..." },
    { "digest": "sha256:b1c4d5e6f7..." }
  ]
}

This is basically a recipe card saying:

“To build this image, stack these layers in this order.”

The manifest itself is usually only a few KB.

Term 4: Complete image / final image

The complete image (or final image) is what you get after stacking all layers together. This is what the running container actually sees.

Important detail: a registry usually does not store one giant fused image file. Instead it stores layers separately and the manifest separately. When someone pulls the image, Docker reconstructs the final image locally. The exception is:

docker save myimage > image.tar

That creates a single fused tarball containing everything.

Term 5: Registry

A registry is a server that hosts Docker images. Examples:

• ECR — AWS Elastic Container Registry
• Docker Hub — the public default registry
• JFrog Artifactory — an enterprise artifact registry

All registries internally store manifests and layers separately.

Term 6: S3 bucket

An S3 bucket is Amazon’s object storage service — think of it as a giant key-value store for files. Registries like ECR often use S3 underneath to physically store layer blobs.

Usually you do not interact with S3 directly. You interact with ECR, Artifactory, or Docker Hub, and they manage storage internally.

Putting it together — docker push

Suppose you run:

docker push myrepo/myapp:v1

Here is what happens:

1. Docker reads the local manifest.
2. For each layer, Docker asks the registry: “Do you already have this digest?”
3. The registry checks storage (often S3 underneath).
4. Existing layers are skipped.
5. Only missing layers are uploaded.
6. The manifest JSON is uploaded last.

Layer	Status
python:3.11 (~900 MB)	already exists
Flask layer (~5 MB)	already exists
app.py layer (~2 KB)	uploaded

Result: only ~2 KB may actually get uploaded. That is the power of layered storage, checksums, and deduplication.

What happens during docker pull

Now your teammate runs:

docker pull myrepo/myapp:v1

Docker does this:

1. Downloads the manifest.
2. Checks the local cache for layers.
3. Downloads only missing layers.
4. Reassembles the image locally.

Layer	Status
python:3.11	already cached
Flask layer	already cached
app.py layer	downloaded

Again, only the changed layer transfers.

Contrast: uploading directly to S3

Instead of using a registry, suppose you do:

docker save myrepo/myapp:v1 > myapp.tar
aws s3 cp myapp.tar s3://my-bucket/

Now S3 stores one giant tarball — with no layer awareness, no manifests, and no deduplication. To use it, someone must:

aws s3 cp s3://my-bucket/myapp.tar .
docker load < myapp.tar

That means downloading the entire image every time — even if only app.py changed.

Registry vs. raw S3

Feature	Registry (ECR / Docker Hub)	Raw S3 tarball
Layer deduplication	Yes	No
Partial downloads	Yes	No
Checksum-aware caching	Yes	No
Manifest support	Yes	No
Efficient updates	Yes	No
Requires full download every time	No	Yes

Cheat sheet

Term	What it is
Layer	Filesystem diff from one Dockerfile step
Checksum / Digest	SHA256 fingerprint of a layer
Manifest	JSON describing layer order
Final image	Result of stacking all layers
Registry	Server hosting Docker images
ECR	AWS-managed Docker registry
JFrog Artifactory	Enterprise artifact registry
Docker Hub	Public Docker registry
S3 bucket	Raw object storage backend

Mental model

Think of a Docker image like LEGO instructions:

• Layers = LEGO pieces
• Manifest = instruction manual
• Registry = warehouse storing LEGO pieces
• Checksums = unique IDs for each piece
• Final image = the completed LEGO model

Docker avoids reshipping identical pieces repeatedly. That’s why container registries are far more efficient than storing giant tarballs directly in S3.

← Back to all posts