pkger

pkger is a packaging tool for MinIO projects that generates DEB, RPM, and APK packages along with download metadata JSON files consumed by min.io/download.

Packaging minio during development

For testing minio packages during development, first install pkger so it's available in your PATH. Then prepare a release directory (such as dist) with architecture-specific subdirectories. For example, create ./dist/linux-amd64 and move your compiled minio binary there, renaming it to include the release version like minio.RELEASE.2025-03-12T00-00-00Z.debug.GIT_TAG. Make sure to replace the timestamp and git tag with your actual values.

You'll also need the minio.service systemd file, which you can download from the minio-service repository:

wget -O minio.service "https://raw.githubusercontent.com/minio/minio-service/refs/heads/master/linux-systemd/minio.service"

Then run pkger with the release version, specifying minio as the app name and using the --ignore flag to continue even if some architectures are missing:

pkger -r RELEASE.2025-03-12T00-00-00Z.debug.GIT_TAG --appName minio --ignore --releaseDir=dist

The packaged files (rpm, deb, apk) along with the downloads JSON metadata will be generated in the ./dist directory.

Packaging sidekick releases

Sidekick releases follow a similar workflow. Create the release directory structure with subdirectories for each supported architecture (amd64 and arm64 only). Place your compiled sidekick binaries in these directories with the release version appended to the filename. Note that sidekick only supports amd64 and arm64 architectures—ppc64le is not included.

mkdir -p ./sidekick-release/linux-amd64 ./sidekick-release/linux-arm64
mv ./sidekick-linux-amd64 ./sidekick-release/linux-amd64/sidekick.RELEASE.2025-03-12T00-00-00Z
mv ./sidekick-linux-arm64 ./sidekick-release/linux-arm64/sidekick.RELEASE.2025-03-12T00-00-00Z

Run pkger with the sidekick app name. By default, it builds all three package formats (RPM, DEB, APK), though you can limit this with the --packager flag:

pkger -r RELEASE.2025-03-12T00-00-00Z --appName sidekick

The generated packages will appear in the architecture-specific directories along with downloads-sidekick.json, which contains download URLs and installation instructions. Note that while APK packages are built, only RPM and DEB installation instructions are included in the JSON metadata.

Packaging warp releases

Warp uses semantic versioning (e.g., v0.4.3) instead of date-based release tags. The version must include the v prefix when you run pkger, but this prefix is automatically stripped in the generated package filenames to follow standard RPM and DEB naming conventions.

Set up the release directories for amd64 and arm64 (warp doesn't support ppc64le):

mkdir -p ./warp-release/linux-amd64 ./warp-release/linux-arm64
mv ./warp-linux-amd64 ./warp-release/linux-amd64/warp.v0.4.3
mv ./warp-linux-arm64 ./warp-release/linux-arm64/warp.v0.4.3

Run pkger with the semantic version. The version must start with v and follow the X.Y.Z format:

pkger -r v0.4.3 --appName warp

The output includes Linux packages (RPM, DEB, APK) in the architecture directories, along with downloads-warp.json. This JSON file includes cross-platform download information for Linux (binary, RPM, DEB), macOS (arm64 binary only), and Windows (amd64 binary). Like sidekick, APK packages are built for Linux but only RPM and DEB installation instructions are documented in the JSON.

Renaming a binary / package (--binary-name, --package-name)

Two optional flags let you rename what a package installs without breaking existing deployments. Both default to the per-app convention, so omitting them produces exactly the same output as before.

• --binary-name overrides the source binary base name read from the release directory (<releaseDir>/<os>-<arch>/<binary-name>.<release>) and the raw-binary filename used in the downloads metadata.
• --package-name overrides the package name and the installed command under /usr/local/bin.

When --package-name differs from the app's default package name, that old name is treated as a legacy name: the package installs a back-compat symlink /usr/local/bin/<old> -> <new> and declares provides/replaces/conflicts on the old name so the previous package is superseded on install.

For example, packaging the enterprise minio server as aistor while keeping the minio command working:

pkger -r RELEASE.2025-03-12T00-00-00Z --appName minio-enterprise \
  --binary-name aistor --package-name aistor

and the enterprise mc client whose binary is ac but whose package/command is acli:

pkger -r RELEASE.2025-03-12T00-00-00Z --appName mc-enterprise \
  --binary-name ac --package-name acli

Upgrading across the rename

On DEB and RPM the renamed package supersedes the old one automatically via the standard install commands — dpkg -i handles the Replaces+Conflicts takeover and dnf/rpm handles Obsoletes — removing the old package and taking over its files.

APK does not auto-remove a package that was explicitly installed (apk reports breaks: world[...]). Existing APK installs must be migrated in two steps:

apk del minio && apk add --allow-untrusted ./aistor_<version>_<arch>.apk

Fresh APK installs of the renamed package work normally.