Mastering base image migrations with Chainguard

Course 8 of 14 in Chainguard Containers Onboarding Guide

Learn how to migrate real apps from “it works on Debian” to minimal, secure Chainguard base images.

Cancel Apply

rate limit

Code not recognized.

About this course

This hands-on course walks you through migrating an application to Chainguard base images, starting on -dev and finishing on distroless. Along the way you’ll practice multi-stage builds, dependency hunting, and common gotchas (e.g., CMD vs ENTRYPOINT, APK vs APT, non-root, and glibc/musl differences). Ideal for teams ready to make Chainguard their new normal.

After this course, you will be able to

  • Explain the difference between app images and base images, and when to use each.
  • Read image specs/SBOMs to understand users, entrypoints, and what’s actually in your image.
  • Convert real-world Dockerfiles to Chainguard using APK (not APT) and run as non-root.
  • Use a -dev image to build, then ship a distroless runtime with a multi-stage Dockerfile.
  • Map and install OS-level dependencies (build vs. runtime), including Python/uv cases.
  • Troubleshoot common pitfalls: CMD vs ENTRYPOINT, missing shells, binary lookups, libc detection.
  • Choose the right path to production: copy-by-binary, Custom Assembly, or the chroot method—and know the tradeoffs.

Curriculum

  • Getting started
  • Why base image migrations matter
  • Setting up your environment
  • Understanding base images
  • Why you can’t just change the FROM line
  • Where to begin with base image migrations
  • Not all languages are the same
  • Dev image migration
  • Introduction to dev image migration
  • Working with APK packages
  • What to do if you can’t find a package
  • Chainguard nuances to watch out for
  • 🛠️ Demo: Migrating to a dev image
  • 🛠️ Demo: Using DFC for dev image migration
  • Multistage build migration
  • Multistage builds and distroless
  • The chroot method for multistage builds
  • Final considerations
  • 🛠️ Demo: Migrating to a distroless multi-stage build
  • Wrap-up
  • Wrapping up: Key takeaways for successful migration
  • Short course feedback

About this course

This hands-on course walks you through migrating an application to Chainguard base images, starting on -dev and finishing on distroless. Along the way you’ll practice multi-stage builds, dependency hunting, and common gotchas (e.g., CMD vs ENTRYPOINT, APK vs APT, non-root, and glibc/musl differences). Ideal for teams ready to make Chainguard their new normal.

After this course, you will be able to

  • Explain the difference between app images and base images, and when to use each.
  • Read image specs/SBOMs to understand users, entrypoints, and what’s actually in your image.
  • Convert real-world Dockerfiles to Chainguard using APK (not APT) and run as non-root.
  • Use a -dev image to build, then ship a distroless runtime with a multi-stage Dockerfile.
  • Map and install OS-level dependencies (build vs. runtime), including Python/uv cases.
  • Troubleshoot common pitfalls: CMD vs ENTRYPOINT, missing shells, binary lookups, libc detection.
  • Choose the right path to production: copy-by-binary, Custom Assembly, or the chroot method—and know the tradeoffs.

Curriculum

  • Getting started
  • Why base image migrations matter
  • Setting up your environment
  • Understanding base images
  • Why you can’t just change the FROM line
  • Where to begin with base image migrations
  • Not all languages are the same
  • Dev image migration
  • Introduction to dev image migration
  • Working with APK packages
  • What to do if you can’t find a package
  • Chainguard nuances to watch out for
  • 🛠️ Demo: Migrating to a dev image
  • 🛠️ Demo: Using DFC for dev image migration
  • Multistage build migration
  • Multistage builds and distroless
  • The chroot method for multistage builds
  • Final considerations
  • 🛠️ Demo: Migrating to a distroless multi-stage build
  • Wrap-up
  • Wrapping up: Key takeaways for successful migration
  • Short course feedback