Debian / Ubuntu Packaging

Building packages

  • Debian packaging is complex enough that it lives in a separate repository: kanidm/kanidm_ppa_automation.
  • While official packages are available at https://kanidm.github.io/kanidm_ppa/ these instructions will guide you through replicating the same process locally, using cross & Docker to isolate the build process from your normal computer and allow building packages for multiple architectures.
  • While the examples below will use aarch64-unknown-linux-gnu aka arm64, the same process works for x86_64-unknown-linux-gnu aka amd64 as well.
  1. Start in the root directory of the main kanidm/kanidm repository.
  2. Install cross: 
    cargo install cross
  3. Pull in the separate deb packaging submodule: 
    git submodule update platform/debian/kanidm_ppa_automation
  4. Launch your desired crossbuild target. Do note the script assumes you use rustup! 
    # See valid targets:
platform/debian/kanidm_ppa_automation/scripts/crossbuild.sh
# Launch a target:
platform/debian/kanidm_ppa_automation/scripts/crossbuild.sh debian-12-aarch64-unknown-linux-gnu
# You can also specify multiple targets within the same distribution:
platform/debian/kanidm_ppa_automation/scripts/crossbuild.sh debian-12-{aarch64,x86_64}-unknown-linux-gnu
  5. Go get a drink of your choice while the build completes.
  6. Create a sacrificial deb builder container to avoid changing your own system: 
    docker run --rm -it -e CI=true \
    --mount "type=bind,src=$PWD,target=/src" \
    --workdir /src \
    rust:bookworm
  7. In the container install dependencies with: 
    # The parameter given is which additional target debian architecture to enable (amd64, arm64, etc.)
# If your native platform is amd64, running with arm64 is enough to cover both archs.
platform/debian/kanidm_ppa_automation/scripts/install_ci_build_dependencies.sh arm64
  8. In the container launch the deb build: 
    platform/debian/kanidm_ppa_automation/scripts/build_debs.sh aarch64-unknown-linux-gnu
# Again, multiple targets also work:
platform/debian/kanidm_ppa_automation/scripts/build_debs.sh {aarch64,x86_64}-unknown-linux-gnu
  9. You can now exit the container, the package paths displayed at the end under target will persist.

Adding or amending a deb package

The rough overview of steps is:

  1. Add cargo-deb specific metadata to the rust package and any static assets. Submit your changes as a PR.
  2. Add build instructions to the separate packaging repo. Submit your changes as a PR.
  3. Go back to the main repo to update the packaging submodule reference to aid running manual dev builds of the new package.

In theory steps 1 & 3 could be done in one PR, but this way is simpler.

Configuration in the main repo

  • The repo is: kanidm/kanidm
  • Packages are primarily based on their package specific Cargo.toml definition read by cargo-deb. For an example, see unix_integration/resolver/Cargo.toml
  • A package specific debian folder is used for static assets. See: unix_integration/resolver/debian for an example.
  • The debian folder may house needed postinst, prerm etc hook definitions. They must include the #DEBHELPER# comment after any custom actions.
  • The package debian folder is also used for any systemd unit files. The file naming pattern is very specific, refer to cargo-deb documentation for details.

Configuration in the kanidm_ppa_automation repo

  • The repo is: kanidm/kanidm_ppa_automation
  • Changes are needed if a new binary and/or package is added, or if build time dependencies change.
  • Amend scripts/crossbuild.sh build rules to include new binaries or packages with shared libraries. Search for the lines starting with cross build.
  • Add any new build time system dependencies to scripts/install_ci_build_dependencies.sh, be aware of any difference in package names between Debian & Ubuntu.
  • Add any new packages to scripts/build_debs.sh, search for the line starting with for package in.
  • Finally, once your changes have been approved go back to the main kanidm/kanidm repo and update the submodule reference and PR the reference update. This is not needed for official builds but helps anyone doing dev builds themselves: 
    cd platform/debian/kanidm_ppa_automation
git pull
cd -
git add platform/debian/kanidm_ppa_automation
git commit -m "Update kanidm_ppa_automation reference to latest"