Heroku's `.deb` Packages Buildpack

heroku/deb-packages is a Heroku Cloud Native Buildpack that adds support for installing Debian packages required by an application that are not available in the build or run image used.

System dependencies on Debian distributions like Ubuntu are described by <package-name>.deb files. These are typically installed using CLI tools such as apt or dpkg. This buildpack implements logic to install packages from .deb files in a CNB-friendly manner that does not require root permissions or modifications to system files that could invalidate how CNB rebasing functionality works.

Important

This is a Cloud Native Buildpack, and is a component of the Heroku Cloud Native Buildpacks project, which is in preview. If you are instead looking for the Heroku Apt Buildpack (for use on the Heroku platform), you may find it here.

This buildpack is compatible with the following environments:

OS	Arch	Distro Name	Distro Version
linux	amd64	Ubuntu	24.04
linux	arm64	Ubuntu	24.04
linux	amd64	Ubuntu	22.04

Usage

Note

Before getting started, ensure you have the pack CLI installed. Installation instructions are available here.

To include this buildpack in your application:

pack build my-app --builder heroku/builder:24 --buildpack heroku/deb-packages

And then run the image:

docker run --rm -it my-app

Configuration

`project.toml`

The configuration for this buildpack must be added to the project descriptor file (project.toml) at the root of your project using the com.heroku.buildpacks.deb-packages table. The list of packages to install must be specified there. See below for the configuration schema and an example.

Default Package Environment Variables

The buildpack includes a set of default environment variables for each package, known as PACKAGE_ENV_VARS. These default environment variables are applied during the build process. However, you can override these default values by specifying environment variables in the project.toml file.

Environment Variables and Post-Install Commands for Skipped Packages

Even if a package is skipped, the environment variables will still be applied. This ensures that any necessary configuration or setup steps are performed, even if the package itself is not installed.

Example

# _.schema-version is required for the project descriptor
[_]
schema-version = "0.2"

# buildpack configuration goes here
[com.heroku.buildpacks.deb-packages]
install = [
  # basic package with some dependencies
  "libgwenhywfar79",
  # child package of "libgwenhywfar79" so we should get a warning that it was already installed by the previous entry
  "libgwenhywfar-data",
  # package with child dependencies skipped so no "libxmlsec1" or "libxmlsec1-openssl" will be installed
  { name = "xmlsec1", skip_dependencies = true },
  # a package already installed on the system
  "wget",
  # libvips is a virtual package which is only provided by libvips42 so no need to halt and ask the user which implementing package to install
  "libvips",
  # curl is already on the system so we're going to force it to be installed
  { name = "curl", force = true },
]

Schema

com.heroku.buildpacks.deb-packages (table, optional)

The root configuration for this buildpack.
- install (array, optional)
  
  A list of one or more packages to install. Each package can be specified in either of the following formats:
  - (string)
    
    The name of the package to install.
  OR
  - (inline-table)
    - name (string, required)
      
      The name of the package to install.
    - skip_dependencies (boolean, optional, default = false)
      
      If set to true, no attempt will be made to install any dependencies of the given package.
    - force (boolean, optional, default = false)
      
      If set to true, the package will be installed even if it's already installed on the system.

Tip

Users of the heroku-community/apt can migrate their Aptfile to the above configuration by adding a project.toml file with:

[_]
schema-version = "0.2"

[com.heroku.buildpacks.deb-packages]
install = [
  # copy the contents of your Aptfile here, e.g.;
  # "package-a",
  # "package-b",
  # "package-c"
]

If your Aptfile contains a package name that uses wildcards (e.g.; mysql-*) this must be replaced with the full list of matching package names.

Environment Variables

The following environment variables can be passed to the buildpack:

Name	Value	Default	Description
`BP_LOG_LEVEL`	`INFO`, `DEBUG`	`INFO`	Configures the verbosity of buildpack output. The `DEBUG` level is a superset of the `INFO` level.

How it works

Detection

This buildpack will pass detection if:

A project.toml file is found at the root of the application source directory

Build

Step 1: Build the package index

Each supported distro is configured to download from the following Ubuntu repositories:

main - Canonical-supported free and open-source software.
universe - Community-maintained free and open-source software.

These repositories comply with the Debian Repository Format so building the list of packages involves:

Downloading the Release file, validating its OpenPGP signature, and caching this in a layer available at build.
Finding and downloading the Package Index entry from the Release for the target architecture and caching this in a layer available at build.
Building an index of Package Name → (Repository URI, Binary Package) entries that can be used to lookup information about any packages requested for install.

Step 2: Determine the packages to install

For each package requested for install declared in the buildpack configuration:

Lookup the Binary Package in the Package Index.
Check if the requested package is already installed on the system
- If it is already installed and the requested package is configured with force = false
  - Skip the package
If the requested package is configured with skip_dependencies = false:
- Add the latest version of the requested package.
- Read the dependencies listed in the Depends and Pre-Depends from the Binary Package.
- For each dependency:
  - Recursively lookup the dependent package and follow the same steps outlined above until all transitive dependencies are added.
If the requested package is configured with skip_dependencies = true:
- Add the latest version of the requested package.

Note

This buildpack is not meant to be a replacement for a fully-featured dependency manager like Apt. The simplistic dependency resolution strategy described above is for convenience, not accuracy. Any extra dependencies added are reported to the user during the build process so, if they aren't correct, you should disable the dependency resolution on a per-package basis with configuration and explicitly list out each package you need installed.

Step 3: Install packages

For each package added after determining the packages to install:

Download the Binary Package from the repository that contains it as a Debian Archive.
Extract the contents of the data.tar entry from the Debian Archive into a layer available at build and launch.
Rewrite any pkg-config files to use a prefix set to the layer directory of the installed package.
Configure the following layer environment variables to be available at both build and launch:

Environment Variable	Appended Values	Contents
`PATH`	`/<layer_dir>/bin` `/<layer_dir>/usr/bin` `/<layer_dir>/usr/sbin`	binaries
`LD_LIBRARY_PATH`	`/<layer_dir>/usr/lib/<arch>` `/<layer_dir>/usr/lib` `/<layer_dir>/lib/<arch>` `/<layer_dir>/lib`	shared libraries
`LIBRARY_PATH`	Same as `LD_LIBRARY_PATH`	static libraries
`INCLUDE_PATH`	`/<layer_dir>/usr/include/<arch>` `/<layer_dir>/usr/include`	header files
`CPATH`	Same as `INCLUDE_PATH`	header files
`CPPPATH`	Same as `INCLUDE_PATH`	header files
`PKG_CONFIG_PATH`	`/<layer_dir>/usr/lib/<arch>/pkgconfig` `/<layer_dir>/usr/lib/pkgconfig`	pc files
`GIT_EXEC_PATH`	`/<layer_dir>/app/.apt/usr/lib/git-core`	git files

Contributing

Issues and pull requests are welcome. See our contributing guidelines if you would like to help.

Testing Locally

To test the project locally, follow these steps:

Prerequisites

Ensure you have the following installed:

Rust and Cargo: Installation Guide
Docker (if applicable for your tests)
cargo install libcnb-cargo

Building the Project

cargo build to build the project cargo test to run the automated tests cargo test --test integration_test to run integration tests cargo libcnb package builds an image of the buildpack that can be used with an application. The output of this command shows usage of the generated image.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Heroku's `.deb` Packages Buildpack

Usage

Configuration

`project.toml`

Default Package Environment Variables

Environment Variables and Post-Install Commands for Skipped Packages

Example

Schema

Environment Variables

How it works

Detection

Build

Step 1: Build the package index

Step 2: Determine the packages to install

Step 3: Install packages

Contributing

Testing Locally

Prerequisites

Building the Project

Files

README.md

Latest commit

History

README.md

File metadata and controls

Heroku's .deb Packages Buildpack

Usage

Configuration

project.toml

Default Package Environment Variables

Environment Variables and Post-Install Commands for Skipped Packages

Example

Schema

Environment Variables

How it works

Detection

Build

Step 1: Build the package index

Step 2: Determine the packages to install

Step 3: Install packages

Contributing

Testing Locally

Prerequisites

Building the Project

Heroku's `.deb` Packages Buildpack

`project.toml`