Document building images from scratch with Apptainer

- Closes #1485

Signed-off-by: Jonathon Anderson <janderson@ciq.com>

CHANGELOG.md

@@ -38,6 +38,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - New `fstab` resource configures mounts in fstab overlay, including NFS mounts. #515
 - Add Dev Container support #1653
 - Add man pages and command reference to userdocs. #1488
+- Document building images from scratch with Apptainer. #1485
 
 ### Changed
 

userdocs/contents/images.rst

@@ -322,79 +322,60 @@ remove any package repository caches that may have been generated.
 Creating Images From Scratch
 ============================
 
-You can also create images from scratch and import those
+It is absolutely possible to create an `OCI base image`_ from scratch, but it is
-images into Warewulf as previous versions of Warewulf did.
+particularly easy to do with Apptainer.
 
-Building An Image From Your Host
+.. _OCI base image: https://docs.docker.com/build/building/base-images/
---------------------------------
 
-RPM based distributions, as well as Debian variants can all bootstrap
+Consider the following file called `warewulf-rockylinux-9.def`:
-mini ``chroot()`` directories which can then be used to bootstrap your
-node's image.
 
-For example, on an RPM based Linux distribution with YUM or DNF, you
+.. code-block:: singularity
-can do something like the following:
+
+   Bootstrap: yum
+   MirrorURL: https://download.rockylinux.org/pub/rocky/9/BaseOS/x86_64/os/
+   Include: dnf
+
+   %post
+   dnf -y install --allowerasing \
+     NetworkManager \
+     basesystem \
+     bash \
+     curl-minimal \
+     kernel \
+     nfs-utils \
+     openssh-server \
+     systemd
+
+   dnf -y remove \
+     glibc-gconv-extra
+   rm -rf /boot/* /run/*
+   dnf clean all
+
+Warewulf cannot directly import a container image from an Apptainer SIF yet, so
+an Apptainer image must be built as a *sandbox*.
 
 .. code-block:: console
 
-   # yum install --installroot /tmp/newroot basesystem bash \
+   # apptainer build --sandbox warewulf-rockylinux-9 warewulf-rockylinux-9.def
-       chkconfig coreutils e2fsprogs ethtool filesystem findutils \
+   [...]
-       gawk grep initscripts iproute iputils net-tools nfs-utils pam \
+   INFO:    Creating sandbox directory...
-       psmisc rsync sed setup shadow-utils rsyslog tzdata util-linux \
+   INFO:    Build complete: warewulf-rockylinux-9
-       words zlib tar less gzip which util-linux openssh-clients \
-       openssh-server dhclient pciutils vim-minimal shadow-utils \
-       strace cronie crontabs cpio wget rocky-release ipmitool yum \
-       NetworkManager
 
-You can do something similar with Debian-based distributions:
+Once a sandbox container image has been built, it can be imported into Warewulf.
 
 .. code-block:: console
 
-   # apt-get install debootstrap
+   # wwctl container import ./warewulf-rockylinux-9 rockylinux-9
-   # debootstrap stable /tmp/newroot http://ftp.us.debian.org/debian
 
-Once you have created and modified your new ``chroot()``, you can
+.. note::
-import it into Warewulf with the following command:
 
-.. code-block:: console
+   Although warewulf does not currently support importing a SIF directly, a SIF can be converted to
+   a sandbox with Apptainer and then imported into Warewulf.
+    
+   .. code-block:: console
 
-   # wwctl image import /tmp/newroot imagename
+      # apptainer build --sandbox my-sandbox my-image.sif
-
+      # wwctl container import ./my-sandbox my-image
-Building An Image Using Apptainer
----------------------------------
-
-Apptainer, an image platform for HPC and performance intensive
-applications, can also be used to create node images for
-Warewulf. There are several Apptainer image recipes in the
-``images/Apptainer/`` directory and can be found on GitHub at
-`https://github.com/warewulf/warewulf/tree/main/images/Apptainer
-<https://github.com/warewulf/warewulf/tree/main/images/Apptainer>`_.
-
-You can use these as starting points and adding any additional steps
-you want in the ``%post`` section of the recipe file. Once you've done
-that, installing Apptainer, building an image sandbox and importing
-into Warewulf can be done with the following steps:
-
-.. code-block:: console
-
-   # yum install epel-release
-   # yum install Apptainer
-   # Apptainer build --sandbox /tmp/newroot /path/to/Apptainer/recipe.def
-   # wwctl image import /tmp/newroot imagename
-
-Building An Image Using Podman
-------------------------------
-
-You can also build an image using podman via a ``Dockerfile``. For
-this step the image must be exported to a tar archive, which then
-can be imported to Warewulf. The following steps will create an
-openSUSE Leap image and import it to Warewulf:
-
-.. code-block:: console
-
-  # podman build -f images/Docker/openSUSE/Imagefile --tag leap-ww
-  # podman save localhost/leap-ww:latest  -o ~/leap-ww.tar
-  # wwctl image import file://root/leap-ww.tar leap-ww
 
 Duplicating an image
 ====================