Skip to content

Latest commit

 

History

History
157 lines (100 loc) · 7.61 KB

custom.md

File metadata and controls

157 lines (100 loc) · 7.61 KB
Raw

Building a custom Debian ISO image

Makefile automates maintenance/build/release procedures (download of extra components, tests and documentation generation, running the build, generating/signing checksums...).

The live/ISO image build process is managed by live-build:

Run make help for a description of available Makefile targets.

Build using the default configuration

Install Debian. You must build from the same distribution as the target distribution (build bookworm systems on a build machine running Debian bookworm, testing systems on a machine running Debian testing...). Then run the following commands:

# install requirements for the build system
sudo apt install make git sudo live-build
# clone the repository
git clone https://gitlab.com/nodiscc/debian-live-config
# build the image
cd debian-live-config && make install_buildenv && make

You need some disk space for the download and build caches. The build directory grows to about 13GB using the default configuration.

Changing the default build configuration

live-build is configured through files under the auto/ and config/ directories.

.
├── auto                        #main live-build configuration
├── config
│   ├── archives                #package mirrors/repositories
│   ├── hooks                   #extra scripts to run during build stages
│   ├── includes.binary         #files to include on the ISO filesystem
│   ├── includes.chroot         #files to include in the live system's filesystem
│   ├── includes.installer      #files to include in the installer's filesystem
│   ├── package-lists
│   │   └── *.list.chroot		#packages to install on the live system
│   │   └── *.list.binary		#packages to place in the APT repository on the ISO image
│   ├── packages.chroot         #standalone .deb packages to install on the live system
│   └── task-lists              #tasksel tasks to install on the live system
├── doc			#user documentation
├── Makefile	#main automation, dependencies management, ...
└── scripts		#extra automation scripts

auto/

  • auto/config sets basic configuration settings for the build (architecture, boot configuration, installer...), see man lb config
  • auto/clean is run automatically before each build to ensure the build directory is free of any artifacts from previous builds (download caches are kept). See man lb clean
  • auto/build contains the command used for the build, and basic logging settings

config/includes.chroot/

Files to copy to the resulting live system (eg. modified configuration or data files under etc/, opt/, usr/, ...)

Scripts and data that do not belong to an existing Debian package should be distributed as custom packages, and not stashed directly into this directory. Debian packages can also handle custom configuration files (see man dpkg-divert).

For example, to add custom files/unpackaged programs inside your live system:

git clone https://gitlab.com/nodiscc/toolbox config/includes.chroot/opt/toolbox
git clone https://gitlab.com/nodiscc/debian-live-config config/includes.chroot/opt/dlc
echo "blacklist nouveau" > config/includes.chroot/etc/modprobe.d/

config/package-lists/

  • *.chroot: lists of packages to install on the resulting image/system
  • *.binary: lists of additional packages to add to the ISO image pool/ directory (to use as an offline repository/mirror) (not required for the live system to work)

Simply use the .list extension to install packages in the live system and include them in the pool/ directory in the ISO image as well.

config/packages.chroot/

.deb packages placed here will be installed to the live system. May be useful when:

  • You need a package that is not available in Debian (see requests for packaging)
  • The package can be downloaded as a standalone .deb on the original project website OR you want to build a package yourself
  • You don't want to add a third-party repository to your APT sources list (see below).

Caveats:

  • Packages placed here will not receive upgrades through APT (unless they are someday added to official Debian repositories)
  • Packages placed here are not GPG-signed. Ensure you download/build the package over a secure channel.

See Makefile.extra for examples.

config/includes.installer/

preseed.cfg is used to preconfigure the installer using preseeding.

config/preseed/

*.chroot.cfg used to preseed debconf values inside the resulting live system.

config/hooks/

Scripts used to run arbitrary commands at different stages of the build (*.hook.chroot or .*chroot.binary). See /usr/share/doc/live-build/examples/hooks/ for examples.

config/archives/

This directory contains lists of APT repositories from which packages will be downloaded during the build [1]. It uses the sources.list format.

config/includes.binary/

Additional files to place at the root of the ISO image filesystem (these files will be directly accessible when mounting the ISO).

Other

Setting the locale/language

Currently only 2 locales (english and french) are pre-generated, other languages have to be manually added to the build configuration, and the ISO rebuilt.

Release process

  • make bump_version, update version indicators, git add changes
  • Update release date in CHANGELOG.md, git add CHANGELOG.md
  • make doc && git add doc/md && git commit -m "release v$new_version"
  • git tag --sign $new_version && git push && git push --tags
  • make && make checksums sign_checksums test_imagesize
  • make tests
    • BIOS mode: test live mode in all languages
    • BIOS mode: test offline installation
    • UEFI mode: test offline installation
    • During installation, test the following disk partitioning schemes:
      • Automatic whole disk encrypted LVM
      • Automated whole disk LVM
      • Automated whole disk partitioning
      • Manual
  • Copy latest CHANGELOG.md entry to a new Github/Gitlab release
  • attach debian-live-config-X.Y.Z-debian-bookworm-amd64.iso debian-live-config-release.key SHA512SUMS SHA512SUMS.sign to the releases
  • Publish release

See also