Repository files navigation

Build apk packages using declarative pipelines.

Commonly used to provide custom packages for container images built withapko. The majorityof apks are built for use with either theWolfi orAlpine Linux ecosystems.

Key features:

• Pipeline-oriented builds. Every step of the build pipeline is defined andcontrolled by you, unlike traditional package managers which have distinctphases.
• Multi-architecture by default. QEMU is used to emulate variousarchitectures, avoiding the need for cross-compilation steps.

Secure software factories are the evolution of DevOps, allowing auser to prove the provenance of all artifacts incorporatedinto a software appliance. By building and capturing softwareartifacts into packages, DevOps teams can manage their softwareartifacts as if they were any other component of an image.

This is especially useful when building software appliances inthe form of OCI container images withapko.

You can install Melange from Homebrew:

brew install melange

You can also install Melange from source:

go install chainguard.dev/melange@latest

You can also use the Melange container image:

docker run cgr.dev/chainguard/melange version

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

docker run --privileged -v"$PWD":/work cgr.dev/chainguard/melange build examples/gnu-hello.yaml

Running outside of a container requiresDocker, but should also work with other runtimes such aspodman.

A melange build file looks like:

package:name:helloversion:2.12epoch:0description:"the GNU hello world program"copyright:    -attestation:|        Copyright 1992, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2005,        2006, 2007, 2008, 2010, 2011, 2013, 2014, 2022 Free Software Foundation,        Inc.      license: GPL-3.0-or-laterdependencies:runtime:environment:contents:repositories:      -https://dl-cdn.alpinelinux.org/alpine/edge/mainpackages:      -alpine-baselayout-data      -busybox      -build-base      -scanelf      -ssl_client      -ca-certificates-bundlepipeline:  -uses:fetchwith:uri:https://ftp.gnu.org/gnu/hello/hello-${{package.version}}.tar.gzexpected-sha256:cf04af86dc085268c5f4470fbae49b18afbc221b78096aab842d934a76bad0ab  -uses:autoconf/configure  -uses:autoconf/make  -uses:autoconf/make-install  -uses:stripsubpackages:  -name:"hello-doc"description:"Documentation for hello"dependencies:runtime:        -foopipeline:      -uses:split/manpagestest:pipeline:        -uses:test/docstest:environment:contents:packages:        -barpipeline:    -runs:|        hello        hello --version

We can build this with:

melange build examples/gnu-hello.yaml

or, with Docker:

docker run --privileged --rm -v"${PWD}":/work \  cgr.dev/chainguard/melange build examples/gnu-hello.yaml

This will create apackages folder, with an entry for each architecture supported by the package. If you only want to build for the current architecture, you can add--arch $(uname -m) to the build command. Inside the architecture directory you should find apk files for each package built in the pipeline.

If you want to sign your apks, create a signing key with themelange keygen command:

melange keygen

 generating keypair with a 4096 bit prime, please wait... wrote private key to melange.rsa wrote public key to melange.rsa.pub

And then pass the--signing-key argument tomelange build.

To include debug-level information on melange builds, edit yourmelange.yaml file and includeset -x in your pipeline. You can add this flag at any point of your pipeline commands to further debug a specific section of your build.

...pipeline:  -name:Build Minicli applicationruns:|      set -x      APP_HOME="${{targets.destdir}}/usr/share/hello-minicli"...

Melange provides the following default substitutions which can be referenced in the build file pipeline:

An example build file pipeline with substitutions:

pipeline:  -name:'Create tmp dir'runs:mkdir ${{targets.destdir}}/var/lib/${{package.name}}/tmp

More detailed documentation

To use a melange built apk in apko, either upload it to a package repository or use a "local" repository. Using a local repository allows a melange build and apko build to run in the same directory (or GitHub repo) without using external storage.An example of this approach can be seen in thenginx-image-demo repo.