Dalec: Declarative Package and Container Builds

Dalec, a Cloud Native Computing Foundation (CNCF) Sandbox project, is a Docker BuildKit frontend that enables users to build system packages and container images from declarative YAML specifications. As a BuildKit frontend, Dalec integrates directly into the Docker build process, requiring no additional tools beyond Docker itself.

Dalec’s primary focus is building native Linux packages (RPM and DEB formats) from source, with optional container image creation from those packages. It supports RPM-based distributions such as Azure Linux, AlmaLinux, and Rocky Linux, as well as DEB-based distributions like Debian and Ubuntu. It also supports pluggable backends for additional operating systems.

By replacing complex spec files and multi-stage Dockerfiles with a single declarative configuration, Dalec simplifies package building while providing built-in support for SBOMs, provenance attestations, and package signing.

Why Dalec?

Building packages traditionally requires:

• Manual creation of distribution-specific spec files (.spec for RPM, debian/ directory for DEB)
• Multi-stage Dockerfiles with complex build logic
• Architecture-specific build configurations
• Separate build processes for each target distribution
• Manual dependency management and bootstrapping

Dalec replaces this complexity with a single declarative YAML specification that defines:

• Sources - Git repositories, HTTP archives, or inline content
• Dependencies - Build-time and runtime package dependencies
• Build steps - Commands to compile and prepare artifacts
• Artifacts - Binaries, configuration files, and systemd units to package
• Targets - Distribution-specific customizations
• Tests - Validation of the built package
• Image config - Optional container image creation from the package

The result is a portable, and auditable build process.

Key Benefits

🐳 Zero Installation - Works with standard Docker. No specialized tooling, package managers, or daemon processes required. If you can run docker build, you can use Dalec.

🚀 Fast and Cacheable - BuildKit’s intelligent caching means rebuilds are lightning fast. Change one source file, rebuild only what’s affected.

🤝 Integration – Dalec integrates at both the package manager level and with language toolchains such as Go and Rust. This allows Dalec to automatically manage caches for items such as Go modules, incremental compiler caches, and packages across builds.

🔒 Secure by Default - Automatic SBOM generation, provenance attestations, and package signing built into the workflow. Supply chain security without extra steps.

📦 Package and Container - Build once, output both. Get installable RPM/DEB packages for traditional deployments AND minimal container images for Kubernetes from the same specification.

🌍 Multi-Distribution - One spec, multiple targets. Build for Ubuntu, Debian, Azure Linux, Rocky Linux, and AlmaLinux without maintaining separate build configurations.

✍️Better Composition - Declarative configurations compose cleanly. You can override specific parts for different distributions or targets without rewriting the entire build logic, and focusing on the package level makes it more natural to break components down into more composable pieces.

🔍 Fully Auditable - Declarative configuration means no hidden build steps. Every artifact’s provenance is traceable, meeting compliance and security requirements.

Who Should Use Dalec?

Dalec makes it easy for different audiences to achieve their goals:

For Application Developers

Convert your source code into distributable packages without learning RPM spec files or Debian packaging conventions. Focus on your application, not build infrastructure.

For Platform Operators

Maintain a consistent build process across your organization. Centralize packaging expertise in reusable specifications instead of scattered Dockerfiles and build scripts. Enforce security and compliance requirements at build time.

For Package Maintainers

Build packages for multiple distributions from a single source of truth. Reduce maintenance burden and ensure consistency across your supported platforms.

How Dalec Works

Dalec is implemented as a BuildKit frontend. When you specify # syntax=ghcr.io/project-dalec/dalec/frontend:latest at the top of your spec file, Docker BuildKit automatically pulls and executes the Dalec frontend, which translates your YAML specification into low-level build instructions (LLB graphs).

The Build Flow:

1. Source acquisition - Clone git repositories, download archives, generate dependency manifests (like Go modules, npm packages, or Python wheels)
2. Package build - Execute build steps in isolated environments with dependencies installed
3. Package creation - Create RPM or DEB packages with artifacts and metadata
4. Package testing - Install and validate the package in a clean environment
5. Container creation (optional) - Install packages into a minimal base image

From a single YAML file, you can generate multi-architecture packages that work across distributions, then optionally compose them into minimal container images—all without writing a single line of Dockerfile or distribution-specific spec.

Real-World Use Cases

Open Source Projects - Distribute your software across multiple Linux distributions without maintaining separate packaging workflows. A single Dalec spec replaces RPM spec files, debian/ directories, and custom build scripts.

Enterprise Deployments - Build compliant, auditable packages for both traditional VM-based deployments and modern Kubernetes clusters. The same build produces installable packages for your data center and container images for your cloud infrastructure.

CI/CD Pipelines - Integrate seamlessly into GitHub Actions, GitLab CI, or any CI system that supports Docker. No special runners or build agents required, just standard Docker.

Security-Critical Applications - Leverage BuildKit's built-in SBOM and provenance generation to meet supply chain security requirements. Every build produces attestations that prove what went into your packages and containers.

Multi-Architecture Builds - Build for x86_64, ARM64, and other architectures with a single command. BuildKit handles the complexity of cross-compilation automatically.

A Simple Example

Here’s what a Dalec spec looks like. This example builds go-md2man, a tool that converts Markdown to man pages:

# syntax=ghcr.io/project-dalec/dalec/frontend:latest
name: go-md2man
version: 2.0.3
revision: "1"
packager: Dalec Example
vendor: Dalec Example
license: MIT
description: A tool to convert markdown into man pages (roff).
website: https://github.com/cpuguy83/go-md2man

sources:
  src:
    generate:
      - gomod: {}  # Pre-downloads Go modules (network disabled during build)
    git:
      url: https://github.com/cpuguy83/go-md2man.git
      commit: v2.0.3

dependencies:
  build:
    golang:

build:
  env:
    CGO_ENABLED: "0"
  steps:
    - command: |
        cd src
        go build -o go-md2man .

artifacts:
  binaries:
    src/go-md2man:

image:
  entrypoint: go-md2man
  cmd: --help

tests:
  - name: Check bin
    files:
      /usr/bin/go-md2man:
        permissions: 0755

From this single YAML file, you can build RPM packages, DEB packages, and container images for multiple distributions and architectures using standard docker build commands.

Dalec can also create minimal container images with just runtime dependencies, no source code building required. This is perfect for creating lightweight containers with only the packages you need.

Here’s a minimal example that creates a container with curl and bash:

# syntax=ghcr.io/project-dalec/dalec/frontend:latest name: my-minimal-image version: 0.1.0 revision: "1" license: MIT description: A minimal image with only curl and shell access dependencies: runtime: curl: bash: image: entrypoint: /bin/bash

Build it with:

docker build -f my-minimal-image.yml --target=azlinux3 -t my-minimal-image:0.1.0 .

This produces a minimal image built from scratch containing only curl, bash, and their dependencies.

Pro tip: You can skip creating a spec file entirely by passing dependencies on the command line:

docker build -t my-minimal-image:0.1.0 --build-arg BUILDKIT_SYNTAX=ghcr.io/project-dalec/dalec/frontend:latest --target=azlinux3/container/depsonly - <<<"$(jq -c '.dependencies.runtime = {"curl": {}, "bash": {}} | .image.entrypoint = "/bin/bash"' <<<"{}")"

Learn more in the Container-only builds documentation.

Getting Started

Ready to build your first package and container image? The Dalec Quickstart walks you through building go-md2man, a real-world example that demonstrates:

• Creating a declarative YAML specification
• Building RPM and DEB packages
• Creating minimal container images
• Multi-architecture builds

The quickstart shows how a single spec can produce packages for multiple distributions (Azure Linux, Ubuntu, Debian) and architectures (x86_64, ARM64) using standard docker build commands.

CI/CD Integration

Dalec integrates seamlessly into any CI/CD system that supports Docker, including GitHub Actions, GitLab CI, Jenkins, and cloud-native build systems. Since Dalec builds use standard docker build commands, no special runners or build agents are required—just a standard Docker environment.

Thanks to BuildKit, Dalec can also build directly on Kubernetes clusters using the Kubernetes driver. This enables scalable, cloud-native builds without requiring dedicated build VMs, making it ideal for large-scale CI/CD pipelines.

This makes it easy to:

• Build and publish packages on every release
• Generate multi-architecture artifacts in parallel
• Integrate SBOM generation and signing into your pipeline
• Push containers to any OCI-compliant registry
• Scale builds elastically on Kubernetes infrastructure

Supply Chain Security

SBOM and Provenance Attestations

BuildKit provides integrated support for Software Bill of Materials (SBOM) generation and provenance attestations. SBOMs automatically catalog every package and dependency in your build, providing complete transparency into what’s inside your artifacts. Provenance attestations are cryptographically-signed records that prove how your image was built, including the source repository, build parameters, and execution environment. This enables verification throughout your deployment pipeline. Learn more about configuring these features in the BuildKit attestations documentation.

Package Signing

Dalec supports GPG signing of packages for additional trust and verification:

package_config:
  signer:
    frontend:
      image: <signer-image>

Signed packages ensure recipients can verify authenticity and detect tampering.

Conclusion

Dalec provides a modern, declarative approach to building system packages and containers. By leveraging Docker BuildKit as a frontend, it eliminates the need for complex build toolchains while providing secure builds across multiple Linux distributions.

For open-source projects that need to distribute both packages and containers, Dalec offers a unified build process that simplifies CI/CD while strengthening supply chain security.

Whether you’re migrating from traditional RPM spec files, consolidating Dockerfiles, or building a new project from scratch, Dalec provides the simplicity of modern container tools with the flexibility of native package formats.

Get Started

Ready to try Dalec? You’re just one docker build command away:

1. Explore the documentation: project-dalec.github.io/dalec
2. Try the quickstart tutorial: Build your first package and container
3. Browse examples: See real-world specs in the examples directory
4. Join the community: Connect with us in the #dalec channel on CNCF Slack
5. Contribute: Dalec is an open-source project under the CNCF. Contributions are welcome! Check out the contributing guide to get involved