Wolfi is the first community Linux (un)distribution declaratively built for creating a secure base layer for your containers!
Wolfi is a Linux OS designed for the container and cloud-native era. Chainguard started the Wolfi project to enable building Chainguard Containers, our collection of curated distroless images that meet the requirements of a secure software supply chain. This required a Linux distribution with components at the appropriate granularity and with support for glibc.
Wolfi is a stripped-down distro designed for the cloud-native era. It doesn't have a kernel of its own, instead relying on the environment (such as the container runtime) to provide one. This separation of concerns in Wolfi means it is adaptable to a range of environments.
Wolfi, whose name was inspired by the world's smallest octopus, has some key features that differentiates it from other distributions that focus on container/cloud-native environments:
- Provides a high-quality, build-time SBOM as standard for all packages
- Packages are designed to be granular and independent, to support minimal images
- Uses the proven and reliable apk package format
- Fully declarative and reproducible build system
- Designed to support glibc
- os contains the core Wolfi OS repository.
| Resource | Details |
|---|---|
| Slack | #apko channel on Kubernetes Slack |
| Forum | See GitHub Discussions |
The community repo contains full details of past community calls and resources.
To get you up and running with Wolfi, let's go over a quick demo where you can create an image from a Dockerfile.
We'll use a "Hello, World" style Python program to demonstrate:
def main():
print("Hello, Wolfi!")
if __name__ == "__main__":
main()Within the same directory, you can create the Dockerfile. This Dockerfile will set up the WORKDIR, and copy relevant files. It will also define the entry point that will be executed when we run this image with docker run. We are using the wolfi-base image to build a Python image from scratch, using Wolfi apks. The final image runs using the unprivileged nonroot user.
FROM cgr.dev/chainguard/wolfi-base
ARG version=3.11
WORKDIR /app
RUN apk add python-${version} && chown -R nonroot:nonroot /app/
USER nonroot
COPY hello_wolfi.py /app/
ENTRYPOINT [ "python", "hello_wolfi.py" ]
This Dockerfile uses a variable called version to define which Python version is going to be installed on the resulting image. You can change this to one of the available Python versions on the wolfi-dev/os repository.
From here, you can build and run your image. If you run into issues with the build step, try using sudo.
docker build . -t hellowolfi
docker run --rm hellowolfiYou should receive the following output:
Hello, Wolfi!
For more guidance, you can check out a full tutorial on Creating Wolfi Images with Dockerfiles, or alternately use apko to build a distroless image with only the packages you need, by reviewing a Getting Started with apko tutorial.
Wolfi is a Linux undistro designed from the ground up to support newer computing paradigms such as containers. Although Wolfi has a few similar design principles as Alpine (such as using apk), it is a different distribution that is focused on supply chain security. Unlike Alpine, Wolfi does not currently build its own Linux kernel, instead relying on the host environment (e.g. a container runtime) to provide one.
Yes, Wolfi is freely available under the Apache License V2 and will always be.
Packages in Wolfi are published to public Wolfi APK Repositories.
Non-latest versions of packages in these repositories are retained for 12 months by default. For more information, see the Wolfi Archive Policy announcement.
No, it’s not possible to mix Alpine apks with Wolfi apks. If your image requires dependencies that are currently only available for Alpine. You might consider using melange to build a custom apk for your image.
No. Desktop distributions require additional software that is out of scope for Wolfi.
Wolfi was created and is currently maintained by Chainguard as the base of Chainguard OS.
We intend for Wolfi to be the core foundation of Chainguard OS and available as open source project for use with minimal packages as used in our free Chainguard Containers.
See SECURITY.md for information about reporting security incidents concerning and consuming security data about Wolfi.
Find details in our repositories, use our community channels and read our documentation.
