Migration Guides on

Overview of migrating to Chainguard Containers

Mon, 22 Jul 2024 12:56:52 +0000

Chainguard Containers are a collection of container images designed for security and minimalism. Many Chainguard Containers are distroless; they contain only an open-source application and its runtime dependencies. These container images do not even contain a shell or package manager, because fewer dependencies reduce the potential attack surface of images.

By minimizing the number of dependencies and thus reducing their potential attack surface, Chainguard Containers inherently contain few to zero CVEs. Chainguard Containers are rebuilt nightly to ensure they are completely up-to-date and contain all available security patches. With this nightly build approach, our engineering team sometimes fixes vulnerabilities before they’re detected.

Tips for migrating to Chainguard Containers

Thu, 29 May 2025 12:56:52 +0000

The process of migrating over to Chainguard Containers isn’t always straightforward. To help customers become acquainted with Chainguard Containers as they go through the migration process, we’ve assembled this list of tips and strategies for migrating over their applications.

Use development variants when you need a shell

Chainguard provides development (or -dev) variants of its containers which include a shell and package manager to allow users to more easily debug and modify the image.

How to Port a Sample Application to Chainguard Containers

Wed, 10 Apr 2024 12:56:52 +0000

Porting Key Points

Chainguard’s distroless Containers have no shell or package manager by default. This is great for security, but sometimes you need these things, especially in builder images. For those cases we have -dev variants (such as cgr.dev/chainguard/python:latest-dev) which do include a shell and package manager.
Chainguard Containers typically don’t run as root, so a USER root statement may be required before installing software. This should be a temporary escalation only; after completing any root-level operations, you should create and switch to a dedicated non-root user (for example, using addgroup and adduser) or use the image’s built-in non-root user. Leaving the container running as root defeats the security purpose of using minimal images.
The -dev variants and wolfi-base / chainguard-base use BusyBox by default, so any groupadd or useradd commands will need to be ported to addgroup and adduser.
The Free tier of Containers provides :latest and :latest-dev versions. Our paid Production Containers offer tags for major and minor versions.
We use apk tooling, so apt install commands will become apk add.
Chainguard Containers are based on glibc and our packages cannot be mixed with Alpine packages.
In some cases, the entrypoint in Chainguard Containers can be different from equivalent container images based on other distros, which can lead to unexpected behavior. You should always check the image’s specific documentation to understand how the entrypoint works.
When needed, Chainguard recommends using a Base Container like chainguard-base or a -dev variant to install an application’s OS-level dependencies.
Although -dev variants are still more secure than most popular container images based on other distros, for increased security on production environments we recommend combining them with a distroless variant in a multi-stage build.

The Sample Application

The application in question is identidock. This application was written for the book Using Docker about ten years ago, which shows that we can still migrate software of this age to a new container while realizing the benefits of a no-to-low CVE count. The application itself will create identicons for a user name, similar to what GitHub generates for users with no avatar. It was designed at the time to demonstrate a “microservices” approach, and as such it’s made up of 3 services:

Migrating Dockerfiles to Chainguard Containers

Mon, 25 Mar 2024 15:56:52 -0700

Chainguard Containers provide enhanced security through minimal design and built-in provenance attestation, requiring some adjustments when migrating from traditional base images. Built on the Wolfi Linux distribution, these images offer compatibility with most applications while significantly reducing attack surface and vulnerabilities.

A general migration process would involve the following steps:

Identify the base image you need. Check out the Chainguard Containers Directory to identify the image that is the closest match to what you currently use. You may also use wolfi-base as a flexible starting point for your experimentation.
Try the -dev variant of the image first. Chainguard Containers typically have a distroless variant, which is very minimal and doesn’t include apk, and a dev variant that contains tooling necessary to build applications and install new packages. Start with the dev variant or the wolfi-base image to have more room for customization.
Identify packages you need to install. Depending on your current base image, you may need to include additional packages to meet dependencies. Refer to the Searching for Packages section for more details on how to find packages. Make sure the packages you intend to install will work with the base image you select — for example, if you select an older base image built with an older release of glibc and want to install newer packages built with a newer release, you will encounter problems. It’s a good rule of thumb to use the newest base image you can with the newest packages that match the build.
Migrate to a distroless image. Evaluate the option of using a Docker multi-stage build to create a final distroless image containing only what you need. Check the Getting Started with Distroless images for more details of how to work with distroless images. Although not required, this process should give you a smaller image with additional safeguards.

There are some differences in Wolfi’s busybox and coreutils packages when compared to their counterparts in distros such as Debian or even Alpine. Some binaries and scripts are not included by default, which contributes to a smaller package size. This was done in order to keep images to a minimum, but be aware that some commands might still be available through separate packages.

The Guardener

Mon, 30 Mar 2026 00:00:00 +0000

The Guardener migrates your Dockerfiles to use Chainguard Containers. It uses AI to iteratively convert instructions, build images, compare results, and fix issues until the Dockerfile works as expected.

You interact with it through chainctl agent dockerfile commands. The AI runs server-side and scans your workspace to perform its analysis. Docker builds and file access remain local to your machine, and only the data necessary for analysis is processed.

Note: The Guardener is in beta.

Dockerfile Converter

Tue, 18 Mar 2025 15:22:20 +0100

Chainguard’s Dockerfile Converter (dfc) was designed to facilitate the process of porting existing Dockerfiles to use Chainguard Containers. The following platforms are currently supported:

Alpine (apk)
Debian / Ubuntu (apt, apt-get)
Fedora / RedHat / UBI (yum, dnf, microdnf)

Note: If you prefer a fully automated approach, The Guardener is an AI-powered agent that can migrate, optimize, and validate your Dockerfiles with minimal manual intervention.

Installation

If you use Homebrew, you can install dfc with:

Migration best practices and checklist

Mon, 03 Feb 2025 10:42:57 +0000

Chainguard container images are designed to be minimal and to include special features for increased security and provenance attestation. Depending on your current base image and customizations, you may need to make some adjustments when migrating your current workloads to use Chainguard Containers. This checklist provides a high-level overview of the steps you should consider when migrating to Chainguard Containers.

Download the PDF version of this checklist here!

Important to know

Most Chainguard Containers don’t have a package manager or a shell by default. These are distroless images intended to be used as slim runtimes for production environments.
For every version of an image, a complimentary standard image is provided with a shell and the apk package manager. These are identified by the -dev suffix and can be customized.
When possible, we recommend using multistage builds that combine a build stage based on a -dev variant and a runtime stage based on a distroless image.
Chainguard Containers typically don’t run as root, so a USER root statement may be required before installing software.
Chainguard Containers are based on apk. If you’re coming from Debian or Ubuntu you’ll need to replace apt commands with their apk equivalents. This also applies for other distros that are not based on apk.
Some images may behave differently than their equivalent in other distros, due to differences in entrypoint and shell availability. Always check the image documentation for usage details.
For a number of our most popular Containers, a full variant (tagged -full) maps to the upstream image to ease initial migration. It’s a useful starting point if your pipeline depends on packages from your previous image, though we recommend moving to a slimmer variant once you’ve migrated. See Full container variants.

Migration checklist

Check the image’s overview page on the Containers Directory for usage details and any compatibility remarks.
Replace your current base image with a standard -dev (such as latest-dev) variant as a starting point.
Add a USER root statement before package installations or other commands that must run as an administrative user.
Replace any instances of apt install (or equivalent) with apk add.
Use apk search on a running container or the APK Explorer tool to identify packages you need – some commands might be available with different names or bundled with different packages.
When copying application files to the image, make sure proper permissions are set.
Switch back to a non-root user so that the image does not run as root by default.
Build and test your image to validate your setup.
Optional: migrate your setup to a multi-stage build that uses a distroless image variant as runtime. Our Getting Started with Distroless guide has detailed information on how to work with distroless images and multi-stage builds.

For detailed migration guidance, please refer to our Migration Docs on Chainguard Academy. For troubleshooting, check our Debugging distroless containers resource.

Compatibility Guides

Thu, 16 Jan 2025 18:42:57 +0000

Image Matcher

Tue, 26 May 2026 00:00:00 +0000

Migration Guides

Thu, 16 Jan 2025 18:42:57 +0000