Skip to content

jonjohnsonjr/melange

This branch is 1000 commits behind chainguard-dev/melange:main.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

30e42b6 · Mar 19, 2024
Mar 7, 2023
Mar 18, 2024
Mar 11, 2024
Jan 2, 2024
Mar 11, 2024
Sep 30, 2023
Feb 29, 2024
May 27, 2023
Mar 19, 2024
Mar 30, 2023
Oct 6, 2023
Mar 30, 2023
Aug 10, 2023
Jan 19, 2024
Jan 30, 2024
Mar 7, 2022
Nov 21, 2023
Oct 5, 2023
Mar 7, 2024
Mar 18, 2024
Mar 18, 2024
Feb 6, 2024
Jan 19, 2024
Dec 4, 2023

Repository files navigation

melange

Build apk packages using declarative pipelines.

Commonly used to provide custom packages for container images built with apko. The majority of apks are built for use with either the Wolfi or Alpine Linux ecosystems.

Key features:

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

Why

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

This is especially useful when building software appliances in the form of OCI container images with apko.

Installation

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 requires Docker, but should also work with other runtimes such as podman.

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

Quickstart

A melange build file looks like:

package:
  name: hello
  version: 2.12
  epoch: 0
  description: "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-later
  dependencies:
    runtime:

environment:
  contents:
    repositories:
      - https://dl-cdn.alpinelinux.org/alpine/edge/main
    packages:
      - alpine-baselayout-data
      - busybox
      - build-base
      - scanelf
      - ssl_client
      - ca-certificates-bundle

pipeline:
  - uses: fetch
    with:
      uri: https://ftp.gnu.org/gnu/hello/hello-${{package.version}}.tar.gz
      expected-sha256: cf04af86dc085268c5f4470fbae49b18afbc221b78096aab842d934a76bad0ab
  - uses: autoconf/configure
  - uses: autoconf/make
  - uses: autoconf/make-install
  - uses: strip

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 a packages 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 the melange 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 to melange build.

Debugging melange Builds

To include debug-level information on melange builds, edit your melange.yaml file and include set -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 application
    runs: |
      set -x
      APP_HOME="${{targets.destdir}}/usr/share/hello-minicli"
...

Default Substitutions

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

Substitution Description
${{package.name}} Package name
${{package.version}} Package version
${{package.epoch}} Package epoch
${{package.full-version}} ${{package.version}}-r${{package-epoch}}
${{package.description}} Package description
${{package.contextdir}} Directory where targets will be stored for main packages and subpackages
${{targets.destdir}} Directory where targets will be stored for main
${{targets.subpkgdir}} Directory where targets will be stored for subpackages

An example build file pipeline with substitutions:

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

More detailed documentation

Usage with apko

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 the nginx-image-demo repo.

About

build APKs from source code

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Go 97.8%
  • Makefile 1.5%
  • Shell 0.7%