Update documentation

kiwi no longer uses debootstrap
OSInside · Aug 3, 2024 · c1a3d7d · c1a3d7d
1 parent 2043a15
commit c1a3d7d
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 35 deletions.
diff --git a/doc/source/image_description/elements.rst b/doc/source/image_description/elements.rst
@@ -467,8 +467,7 @@ bootstrap_package="package_name":
   in :file:`/var/lib/bootstrap/PACKAGE_NAME.ARCH.tar.xz`.
   The tarball will be unpacked and used as the bootstrap
   rootfs to begin with. This allows for an alternative bootstrap
-  method preventing the use of `debootstrap`. For further details
-  see :ref:`debootstrap_alternative`.
+  method. For further details see :ref:`debianbootstrap_alternative`.
 
 compressed="true|false":
   Specifies whether the image output file should be
@@ -1259,7 +1258,7 @@ components="name"
 
 distribution="name"
   Used for Debian (apt) based repositories only. Specifies the
-  distribution name to be used on call of `debootstrap`
+  distribution name used in the repository data structure.
 
 imageonly="true|false"
   Specifies whether or not this repository should be configured in

diff --git a/doc/source/working_with_images.rst b/doc/source/working_with_images.rst
@@ -35,4 +35,4 @@ Working with Images
    working_with_images/build_with_profiles
    working_with_images/build_in_buildservice
    working_with_images/use_suse_media
-   working_with_images/build_without_debootstrap
+   working_with_images/build_without_debianbootstrap
diff --git a/...with_images/build_without_debootstrap.rst → ..._images/build_without_debianbootstrap.rst b/...with_images/build_without_debootstrap.rst → ..._images/build_without_debianbootstrap.rst
@@ -1,32 +1,28 @@
-.. _debootstrap_alternative:
+.. _debianbootstrap_alternative:
 
-Circumvent debootstrap
-======================
+Circumvent Debian Bootstrap
+===========================
 
 .. sidebar:: Abstract
 
    This page provides information how to build Debian based
-   images with `apt` but without using `debootstrap` to bootstrap
-   the image root tree
-
-When building Debian based images {kiwi} uses two tools to
-create the image root tree. First it calls `debootstrap` to
-initialize a minimal root tree and next it chroot's into that
-tree to complete the installation via `apt`. The reason why it
-is done that way is because `apt` does not(yet) support to
-install packages into an empty root directory like it is done
-with all other packagemanager interfaces implemented in {kiwi}.
-
-The use of `debootstrap` comes along with some prerequisites
-and limitations:
-
-* It can only use one repository to bootstrap from
-* It can only use an official archive repo
-* It has its own dependency resolver different from apt
-
-If one ore more of this properties turns into an issue, {kiwi}
-allows for an alternative process which is based on a prebuilt
-bootstrap-root archive provided as a package.
+   images without an extra bootstrap process.
+
+When building Debian based images {kiwi} uses `apt` in the
+bootstrap and the system phase to create the image root tree.
+However, `apt` does not support a native way to bootstrap
+an empty root tree. Therefore the bootstrap phase uses
+apt only to resolve the given bootstrap packages and to
+download these packages from the given repositories.
+The list of packages is then manually extracted into the
+new root tree which is not exactly the same as if `apt`
+would have installed them natively. For the purpose of
+creating an initial tree to begin with, this procedure
+is acceptable though.
+
+If, for some reasons, this bootstrap procedure is not
+applicable, {kiwi} allows for an alternative process which is
+based on a prebuilt bootstrap-root archive provided as a package.
 
 To make use of a `bootstrap_package`, the name of that package
 needs to be referenced in the {kiwi} description as follows:
@@ -54,10 +50,10 @@ How to Create a bootstrap_package
 ---------------------------------
 
 Changing the setup in {kiwi} to use a `bootstrap_package` rather
-then letting `debootstrap` do the job comes with the task to create
-that package providing the bootstrap root tree. There are more than
-one way to do this. The following procedure is just one example and
-requires some background knowledge about the Open Build Service
+then using {kiwi}'s debian bootstrap method to do the job, comes with
+the task to create that package providing the bootstrap root tree. There
+are more than one way to do this. The following procedure is just one
+example and requires some background knowledge about the Open Build Service
 `OBS <https://build.opensuse.org>`__ and its {kiwi} integration.
 
 1. Create an OBS project and repository setup that matches your image target
@@ -89,12 +85,27 @@ requires some background knowledge about the Open Build Service
           </repository>
 
           <packages type="image">
-              <!-- packages included so OBS adds it as a build dependency, however this is installed by debootstrap -->
-              <package name="mawk"/>
+              <package name="gawk"/>
+              <package name="util-linux"/>
+              <package name="systemd"/>
+              <package name="init"/>
+              <package name="gnupg"/>
+              <package name="iproute2"/>
+              <package name="iptables"/>
+              <package name="iputils-ping"/>
+              <package name="ifupdown"/>
+              <package name="isc-dhcp-client"/>
+              <package name="netbase"/>
+              <package name="dbus"/>
+              <package name="xz-utils"/>
+              <package name="usrmerge"/>
+              <package name="language-pack-en"/>
           </packages>
 
           <packages type="bootstrap">
-              <!-- bootstrap done via debootstrap -->
+              <package name="apt-utils"/>
+              <package name="debconf"/>
+              <package name="mawk"/>
           </packages>
       </image>