Back to Blog
team@tinypod.app

Understanding Container Images: Layers, Tags, and Digests

Container images are the building blocks of self-hosted apps. Understanding layers, tags, and digests helps you manage them effectively.

dockercontainersimagesfundamentals

What Is a Container Image?


An image is a read-only template that contains everything needed to run an application: code, runtime, libraries, and configuration.


Layers


Images are built in layers. Each instruction in a Dockerfile creates a new layer.


FROM node:20-alpine # Layer 1: Base OS + Node.js

COPY package.json . # Layer 2: Package file

RUN npm install # Layer 3: Dependencies

COPY . . # Layer 4: Application code


Why Layers Matter

  • Layers are cached. If package.json didn't change, Layer 2 and 3 are reused.
  • Layers are shared. Two images based on node:20-alpine share the base layer.
  • Layer order matters. Put frequently-changing layers last.

    • Tags


    Tags are human-readable labels for specific image versions.


    postgres:16.2-alpine

    └ image name └ tag


    Common Tag Patterns

  • postgres:16: Major version (auto-updates minor/patch)
  • postgres:16.2: Specific version (pinned)
  • postgres:latest: Latest version (dangerous in production)
  • postgres:16-alpine: Alpine Linux variant (smaller)

    • Never Use :latest in Production

    :latest changes unpredictably. Yesterday it was 16.1, today it's 16.2. Pinned versions prevent surprise breakage.


    Digests


    A digest is a SHA-256 hash of the image. Immutable and unique.

    postgres@sha256:abc123...


    Use digests for maximum reproducibility. The same digest always produces the same image.


    Multi-Architecture Images


    Modern images support multiple CPU architectures:

  • linux/amd64: Intel/AMD servers and laptops
  • linux/arm64: ARM servers, Apple Silicon, Raspberry Pi

    • Docker/Podman automatically pulls the correct architecture.


    Image Size


    Smaller images are better:

  • Faster pulls and deploys
  • Less disk usage
  • Fewer vulnerabilities (less software = less attack surface)

    • Compare: postgres:16 (400 MB) vs postgres:16-alpine (80 MB)


    Managing Images


    List images

    docker images


    Remove unused

    docker image prune (removes dangling images)

    docker image prune -a (removes all unused images)


    Check size

    docker system df


    Regularly prune unused images to reclaim disk space.