Building systemd-nspawn Containers with Debootstrap

On the Debian operating system, debootstrap serves as the foundational provisioning tool that constructs the root filesystem required by systemd-nspawn to run isolated container environments. While systemd-nspawn provides the virtualization layer using Linux namespaces and control groups, it lacks a mechanism to download or assemble an operating system from scratch. debootstrap bridges this gap by fetching, unpacking, and configuring a minimal Debian base installation into a specified target directory, which systemd-nspawn can immediately boot or execute as a lightweight, fully isolated container.

The Division of Labor

Creating an isolated container natively in Debian requires two distinct phases: root filesystem creation and execution virtualization.

  • debootstrap (Filesystem Builder): Connects to official Debian repositories, resolves core dependencies, downloads the essential .deb packages, and unpacks them to establish a functional directory tree (/bin, /etc, /usr, /lib, etc.). It executes initial package configurations, producing an authentic, clean Debian environment identical to a bare-bones system install.
  • systemd-nspawn (Namespace Manager): Accepts the directory created by debootstrap and virtualizes process trees, IPC, network, and mount namespaces. It uses cgroups for resource management and acts as a lightweight alternative to full hypervisors like KVM or application runtimes like Docker.

How Debootstrap Prepares the Container

debootstrap is executed by pointing it toward a target suite (such as bookworm or trixie), a destination path, and a mirror URL:

debootstrap --include=systemd,dbus bookworm /var/lib/machines/my-container http://deb.debian.org/debian

During this operation, debootstrap performs the following critical roles:

  1. Base System Initialization: It installs essential utilities, including package management (dpkg and apt), the GNU C library, and standard Unix command-line utilities.
  2. Service Readiness: By adding packages like systemd and dbus during the debootstrap phase, the target rootfs becomes capable of full init-style booting rather than functioning merely as a chroot shell.
  3. Clean Host Separation: Because debootstrap constructs the environment completely independent of the host’s installed packages, the container maintains its own configuration files, package database, and dependency graph.

Execution and Management

Once debootstrap completes the directory structure, the container is ready for management via standard systemd tooling. An administrator can boot the container using:

systemd-nspawn -D /var/lib/machines/my-container -b

Placing the debootstrap output in /var/lib/machines integrates the directory directly with Debian's machinectl utility. This allows the administrator to start, stop, clone, power off, or inspect the container as a managed system service (systemd-nspawn@my-container.service), fully bridging the gap between a static package directory and a dynamic, running container instance.