read

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:

Live Systems manual
man lb config
man lb build
man lb clean
man live-build
/usr/share/doc/live-manual/pdf/live-manual.portrait.en.a4.pdf.gz (live-manual package)

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.