Docker Packaging

🧪 Experimental

This repository is considered EXPERIMENTAL and under active development until further notice. Please refer to docker-ce-packaging repository to request changes to the packaging process.

About

This repository creates packages (deb, rpm, static) for various projects and are published as a Docker image on Docker Hub.

---

• Packaging guidelines
• Release
• Build
  • Requirements
  • Usage
  • Remote override
• Contributing

Packaging guidelines

Docker-maintained .deb and .rpm packages must build shipped binaries from source in the distro package build path. See PACKAGING.md for the full packaging contract around source builds, distro build environments, provenance, and SBOMs.

Release

Packages are published to Docker Hub as non-runnable images that only contains the artifacts. You can check the GitHub Releases for the list of published Docker tags.

Note

We are also publishing nightly builds using the nightly-<project>-<version> tags.

For testing purpose you can use a tool like Undock to extract packages:

# extract packages for all platforms and output to ./bin/undock folder
$ undock --wrap --rm-dist --all dockereng/packaging:buildx-v0.9.1 ./bin/undock

Build

Requirements

• Docker 20.10 or newer
• Buildx 0.21.0 or newer

Before building packages, you need to use a compatible Buildx driver to be able to build multi-plaform packages such as docker-container:

# create docker-container builder and use it by default
# https://docs.docker.com/build/building/drivers/docker-container/
$ docker buildx create --driver docker-container --name mybuilder --use --bootstrap

Note

Some packages don't have cross-compilation support, and therefore QEMU will be used. As it can be slow to build, it is recommended to use a builder with native nodes.

Usage

# build all packages for all distros
$ docker buildx bake pkg
# build buildx package for debian 12
$ docker buildx bake pkg-buildx-debian12
# build buildx package for debian 12
$ docker buildx bake pkg-buildx-debian12
# build all packages for all distros (only local platform)
$ LOCAL_PLATFORM=1 docker buildx bake pkg

To create a new release for a package:

# build all distros for buildx v0.24.0 and output to ./bin folder
$ PKG_REF=v0.24.0 docker buildx bake pkg-buildx-*
# build and push image to dockereng/packaging:buildx-v0.24.0. "release" target
# will use the "bin" folder as named context to create the image with artifacts
# previously built.
$ docker buildx bake --push --set *.tags=dockereng/packaging:buildx-v0.24.0 release-buildx 

Remote override

Downstream repositories can reuse this repository as a remote Bake definition and extend it with a local docker-bake.override.hcl file instead of forking the full docker-bake.hcl.

Example local override:

variable "PKGS_EXTRA" {
  default = ["my-package"]
}

variable "PKG_PLATFORMS_EXTRA" {
  default = {
    my-package = ["linux/amd64"]
  }
}

variable "PKG_CONTEXTS_EXTRA" {
  default = {
    my-package = "cwd://pkg/my-package"
  }
}

target "_pkg-my-package" {
  dockerfile = "cwd://pkg/my-package/Dockerfile"
  args = {
    PKG_NAME = "my-package"
    PKG_REPO = "https://github.com/example/my-package.git"
    PKG_REF = "main"
  }
}

Example invocation from the downstream repository:

$ docker buildx bake \
  -f docker-bake.hcl \
  -f cwd://docker-bake.override.hcl \
  "https://github.com/docker/packaging.git#main" \
  pkg-my-package-debian12

Use the cwd:// prefix for local files and directories when combining a local override with a remote Bake definition. Without it, Bake resolves paths relative to the remote context instead of the current working directory.

Contributing

Want to contribute? Awesome! You can find information about contributing to this project in the CONTRIBUTING.md