Skip to content

chainguard-dev/apko

BranchesTags

Repository files navigation

apko: apk-based OCI image builder

Build and publish OCI container images built from apk packages.

apko has the following key features:

  • Fully reproducible by default. Run apko twice and you will get exactly the same binary.
  • Fast. apko aims to build images in ms.
  • Small. apko generated images only contain what's needed by the application, in the style of distroless.
  • SBOM Support. apko produces a Software Bill of Materials (SBOM) for images, detailing all the packages inside.
  • Services. apko supports using the s6 supervision suite to run multiple processes in a container without reaping or signalling issues.

Please note that apko is a work in progress and details are subject to change!

Installation

You can install apko from Homebrew:

brew install apko

You can also install apko from source:

go install chainguard.dev/apko@latest

You can also use the apko container image:

docker run cgr.dev/chainguard/apko version

To use the examples, you'll generally want to mount your current directory into the container, e.g.:

docker run -v "$PWD":/work cgr.dev/chainguard/apko build examples/alpine-base.yaml apko-alpine:edge apko-alpine.tar

Alternatively, if you're on a Mac, you can use Lima to run an Alpine Linux VM.

Quickstart

An apko file for building an Alpine base image looks like this:

contents:
  repositories:
    - https://dl-cdn.alpinelinux.org/alpine/edge/main
  packages:
    - alpine-base

entrypoint:
  command: /bin/sh -l

# optional environment configuration
environment:
  PATH: /usr/sbin:/sbin:/usr/bin:/bin

We can build this with apko from any environment with apk tooling:

apko build examples/alpine-base.yaml apko-alpine:test apko-alpine.tar
...
2022/04/08 13:22:31 apko (aarch64): generating SBOM
2022/04/08 13:22:31 building OCI image from layer '/tmp/apko-3027985148.tar.gz'
2022/04/08 13:22:31 OCI layer digest: sha256:ba034c07d0945abf6caa46fe05268d2375e4209e169ff7fdd34d40cf4e5f2dd6
2022/04/08 13:22:31 OCI layer diffID: sha256:9b4ab6bb8831352b25c4bd21ee8259d1f3b2776deec573733291d71a390157bb
2022/04/08 13:22:31 output OCI image file to apko-alpine.tar

or, with Docker:

docker run -v "$PWD":/work cgr.dev/chainguard/apko build examples/alpine-base.yaml apko-alpine:test apko-alpine.tar

You can then load the generated tar image into a Docker environment:

docker load < apko-alpine.tar
Loaded image: apko-alpine:test
docker run -it apko-alpine:test
e289dc84c4ad:/# echo boo!
boo!

You can also publish the image directly to a registry:

apko publish examples/alpine-base.yaml myrepo/alpine-apko:test

See the docs for details of the file format and the