CustomDebian11LiveISO_CLI/doc/md/custom.md

Building a custom Debian ISO image

Makefile contains basic automation/preparation for the build process (download of extra components, tests and documentation generation, running the build, generating/signing checksums...)

The actual ISO image build process is managed by the live-build suite of tools. For more details, read the live-build documentation:

• 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 stable systems on a build machine running Debian stable, testing systems on a machine running Debian testing...). The run the following commands (as root):

# install requirements
apt install make git sudo live-build

# clone the repository
git clone https://gitlab.com/nodiscc/debian-live-config

# build the ISO 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/dlc config/includes.chroot/opt/dlc

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.

# example addition of a third-party program
mkdir -pv config/packages.chroot
wget -N -nv --show-progress -P config/packages.chroot/ https://download.opensuse.org/repositories/home:/strycore/Debian_9.0/amd64/lutris_0.5.2.2_amd64.deb

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/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
• Update the changelog
• git tag --sign $new_version
• make doc && git add doc/md/packages/ doc/md/index.md && git commit -m "update auto-generated documentation"
• make && make checksums && make sign_checksums
• make tests
  • BIOS mode: test live mode in all languages
  • BIOS mode: test online installation
  • BIOS mode: test offline installation
  • UEFI mode: test online 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

See also

• https://stdout.root.sx/links/?searchtags=debian