Dev : Using Qubes Builder v2

Testing Team 4.2 Testing
2

Second guide : build and install your first template

In this guide, you will learn how to build the debian-12-minimal template with Qubes Builder 2.

You will use the qbuilder app vm as a docker executor to build the packages for the vm-bookworm distribution, then build the rpm debian-12-minimal template.

Configuration

In the qbuilder app qube, go to the ~/qubes-builderv2 directory, then update your Qubes Builder v2 configuraton file (builder.yml). I didn’t change the builder.yml, I changed directly the example-configs/qubes-os-r4.2.yml file to use the docker executor and added the debian-12-minimal template :

diff --git a/example-configs/qubes-os-r4.2.yml b/example-configs/qubes-os-r4.2.yml
index f2e391e..96135f8 100644
--- a/example-configs/qubes-os-r4.2.yml
+++ b/example-configs/qubes-os-r4.2.yml
@@ -29,6 +29,11 @@ templates:
       flavor: xfce
       options:
         - firmware
+  - debian-12-minimal:
+      dist: bookworm
+      flavor: minimal
+      options:
+        - firmware
   - whonix-gateway-17:
       dist: bookworm
       flavor: whonix-gateway
@@ -187,15 +192,15 @@ components:
   - openssh
 
 
-#executor:
-#  type: docker
-#  options:
-#    image: "qubes-builder-fedora:latest"
-
 executor:
-  type: qubes
+  type: docker
   options:
-    dispvm: "@dispvm"
+    image: "qubes-builder-fedora:latest"
+
+#executor:
+#  type: qubes
+#  options:
+#    dispvm: "@dispvm"
 
 stages:
   - fetch

And I used this file with the qb’s --builder-conf option.

You can also get inspiration from the official builder.yaml, see the below first resources.

Build

  1. Get (fetch) the git repositories for the packages of the builder-debian component (i.e. all the debian components) with ./qb package fetch :
./qb --debug --verbose --builder-conf example-configs/qubes-os-r4.2.yml --log-file pfetch.log -c builder-debian package fetch
ls -l artifacts/sources/
  1. Build all the packages for the vm-bookworm distribution (bookworm is the debian-12 release name) with ./qb package all :
./qb --debug --verbose --builder-conf example-configs/qubes-os-r4.2.yml --log-file pall.log -d vm-bookworm package all
find artifacts/components/ -name "*.deb"

The built packages are in the artifacts/components/<component>/<package version>/vm-bookworm/ directories.

  1. Build the debian-12-minimal template
    The template delivery container is a rpm.
./qb --debug --verbose --builder-conf example-configs/qubes-os-r4.2.yml --log-file tpl.log -t debian-12-minimal template all

Note: this process use some disk storage, I updated my qbuilder app qube private disk storage to 60GB (I updated the first guide).

Inspect the template rpm file

Result file:

[user@qbuilder qubes-builderv2]$ ls -alh artifacts/templates/rpm/qubes-template-debian-12-minimal-4.2.0-202508062221.noarch.rpm 
-rw-r--r--. 1 user user 755M Aug  6 22:51 artifacts/templates/rpm/qubes-template-debian-12-minimal-4.2.0-202508062221.noarch.rpm

The rpm metadata:

Summary 
[user@qbuilder qubes-builderv2]$ rpm -qi artifacts/templates/rpm/qubes-template-debian-12-minimal-4.2.0-202508062221.noarch.rpm 
Name        : qubes-template-debian-12-minimal
Version     : 4.2.0
Release     : 202508062221
Architecture: noarch
Install Date: (not installed)
Group       : Unspecified
Size        : 3157176383
License     : GPLv3+
Signature   : (none)
Source RPM  : qubes-template-debian-12-minimal-4.2.0-202508062221.src.rpm
Build Date  : Wed Aug  6 22:31:31 2025
Build Host  : a9e72c0ced94
URL         : http://www.qubes-os.org
Summary     : Qubes OS template for debian-12-minimal
Description :
Qubes OS template for debian-12-minimal.

The rpm content :

Summary 
[user@qbuilder qubes-builderv2]$ rpm -ql artifacts/templates/rpm/qubes-template-debian-12-minimal-4.2.0-202508062221.noarch.rpm 
/var/lib/qubes/vm-templates/debian-12-minimal
/var/lib/qubes/vm-templates/debian-12-minimal/apps
/var/lib/qubes/vm-templates/debian-12-minimal/apps.tempicons
/var/lib/qubes/vm-templates/debian-12-minimal/apps.templates
/var/lib/qubes/vm-templates/debian-12-minimal/clean-volatile.img.tar
/var/lib/qubes/vm-templates/debian-12-minimal/netvm-whitelisted-appmenus.list
/var/lib/qubes/vm-templates/debian-12-minimal/private.img
/var/lib/qubes/vm-templates/debian-12-minimal/root.img
/var/lib/qubes/vm-templates/debian-12-minimal/root.img.part.00
/var/lib/qubes/vm-templates/debian-12-minimal/root.img.part.01
/var/lib/qubes/vm-templates/debian-12-minimal/root.img.part.02
/var/lib/qubes/vm-templates/debian-12-minimal/template.conf
/var/lib/qubes/vm-templates/debian-12-minimal/vm-whitelisted-appmenus.list
/var/lib/qubes/vm-templates/debian-12-minimal/volatile.img
/var/lib/qubes/vm-templates/debian-12-minimal/whitelisted-appmenus.list

Install

Copy the template rpm to dom0, then install it with qvm-template:

[user@dom0 Templates]$ qvm-template install --nogpgcheck ./qubes-template-debian-12-minimal-4.2.0-202508062221.noarch.rpm 
Installing template 'debian-12-minimal'...
debian-12-minimal: Importing data

And test it :

[user@dom0 Templates]$ qvm-ls | grep debian-12-minimal
debian-12-minimal          Halted   TemplateVM    black   -                       -
test-d12-min-diy           Running  AppVM         red     debian-12-minimal       sys-firewall

What’s next ?

Now that you know how to build a template, you can

  • read the official builder.yml files to understand them
  • understand the official Qubes Builder v2 documentation
  • customize the template, or test with a specific package or package list
  • experiment to build and test a debian-13 (vm-trixie distribution).
  • build a dom0 (host-fc37 distribution)
  • build a r4.2 install iso
  • …

Resources:

3 Likes