# Introduction

> Source: https://www.ymotongpoo.com/books/chainguard-image-toolchain/00-introduction/


Chainguard is a security company focused on reducing vulnerabilities in container images. Its [Chainguard Images](https://images.chainguard.dev/) are known as **distroless** images that contain almost no known CVEs, and many companies, including Grafana Labs, adopt them as base images. Grafana Labs' [xk6](https://github.com/grafana/xk6/blob/3b5a796179b8f5e714fe25d9806e6ab44ea75e50/Dockerfile#L3), for example, switched its build image to `cgr.dev/chainguard/go` to address CVEs.

The word distroless is nothing new. Google's [distroless](https://github.com/GoogleContainerTools/distroless) project came first, and the idea of a minimal image without a shell or package manager is already widely known. What sets Chainguard apart is that it doesn't hand-carve that minimal image each time. Instead, it generates images mechanically and reproducibly from source, using two OSS tools, **melange** and **apko**, together.

This book follows these two tools in order to work out, hands-on, how Chainguard's image build pipeline is put together. It assumes readers who normally build container images with Dockerfiles and have wondered about their reproducibility or the accuracy of their SBOMs. No prior experience with Alpine Linux is assumed, but a basic understanding of how containers work (layers, the OCI image format) is.

## Why Chainguard built its own tools from scratch

Chainguard was founded in October 2021 by five people — Dan Lorenc, Matt Moore, Kim Lewandowski, Ville Aikas, and Scott Nichols — all of whom had worked on projects like Kubernetes, Sigstore, and distroless at Google. The [blog post](https://www.chainguard.dev/unchained/introducing-chainguard-inc) announcing the founding states the company's mission:

> Security in software supply-chains must be holistic; it cannot be bolted on. The easy way must be the secure way.

The post cites [Sonatype's finding that supply-chain attacks grew 650% in 2021](https://www.sonatype.com/blog/2021-state-of-the-software-supply-chain) and the US [Executive Order 14028](https://www.federalregister.gov/documents/2021/05/17/2021-10460/improving-the-nations-cybersecurity), which framed supply-chain security as a threat to national infrastructure. Around this time, the [supply-chain attack on SolarWinds' products](https://www.cisa.gov/news-events/directives/ed-21-01-mitigate-solarwinds-orion-code-compromise-closed) and the [Log4Shell vulnerability in Apache Log4j](https://logging.apache.org/log4j/2.x/security.html) (CVE-2021-44228) surfaced one after another, and the industry increasingly recognized that not being able to accurately account for a software's components after the fact is itself a risk.

The reasons customers value distroless images, SBOMs, and low CVE counts extend from this same context. [Chainguard's website](https://www.chainguard.dev/about-us) cites compliance with regulatory frameworks such as FedRAMP, PCI DSS, CMMC 2.0, and SOC 2, and claims that adopting its images yields an average 97.6% reduction in CVEs and an 85% reduction in attack surface. In audits and regulatory contexts, being able to explain exactly what's inside an image, after the fact, is itself valuable.

To this end, Chainguard didn't simply use existing distributions like Alpine Linux, Ubuntu, or Debian — it built a new distribution called Wolfi. Chapter 3 covers the reasons for this in more depth.

## The two tools this book covers, and their roles

The two tools each live in their own independent GitHub repository, but they're tightly coupled:

- **melange** ([chainguard-dev/melange](https://github.com/chainguard-dev/melange)): builds source code and produces packages in the APK format, which comes from Alpine Linux.
- **apko** ([chainguard-dev/apko](https://github.com/chainguard-dev/apko)): assembles OCI container images purely from APK packages, without a Dockerfile.

On top of these, [**Wolfi**](https://github.com/wolfi-dev/os), a Linux distribution maintained by Chainguard, serves as the foundation. Every package in Wolfi is built with melange, and apko treats Wolfi's APK repository as its primary source of material.

Figure 1 shows the flow from source code to a published container image.

![How melange and apko work together](20260901-toolchain-overview.png)
*Figure 1: Source code is built into an APK package by melange. apko combines that package with Wolfi's published packages to assemble an OCI image from APKs alone, then publishes it to a registry.*

## How this book is organized

This book alternates between conceptual explanations and hands-on exercises. Chapter 2 looks concretely at the problems with traditional Dockerfile-based image builds. Chapter 3 establishes where the Wolfi distribution fits in, after which Chapters 4 and 5 cover melange's design and a hands-on exercise, and Chapters 6 and 7 cover apko's design and a hands-on exercise. Chapter 8 pulls together how the two tools cooperate, and Chapter 9 looks at how everything covered so far comes together in Chainguard Images' actual production use. Chapter 10 wraps up with a look back at the whole book.

Wherever possible, the command examples in each hands-on chapter were actually run and verified. Anywhere that wasn't possible, the text notes that the example comes from the official repository's examples or documentation.