qusal/salt/qubes-builder
Ben Grande 383c840f2f
doc: lint markdown files
Only way to have a unified markdown syntax is to enforce the wanted
syntax by linting the files. Don't rely on the many markdown syntaxes,
be consistent.
2024-07-04 17:27:31 +02:00
..
files feat: deploy Qusal Builder configuration 2024-06-26 00:18:44 +02:00
clone.sls refactor: initial commit 2023-11-13 14:33:28 +00:00
clone.top refactor: initial commit 2023-11-13 14:33:28 +00:00
configure-qubes-executor.sls chore: copyright update 2024-01-29 16:49:54 +01:00
configure-qubes-executor.top refactor: initial commit 2023-11-13 14:33:28 +00:00
configure-qusal.sls feat: deploy Qusal Builder configuration 2024-06-26 00:18:44 +02:00
configure-qusal.top feat: deploy Qusal Builder configuration 2024-06-26 00:18:44 +02:00
configure.sls fix: use mirrors metalink as a submodule 2024-07-04 11:24:21 +02:00
configure.top refactor: initial commit 2023-11-13 14:33:28 +00:00
create.sls refactor: prefer systemd sockets over socat 2024-06-25 22:16:26 +02:00
create.top refactor: initial commit 2023-11-13 14:33:28 +00:00
init.sls refactor: initial commit 2023-11-13 14:33:28 +00:00
init.top refactor: initial commit 2023-11-13 14:33:28 +00:00
install-dev.sls feat: add development goodies to Qubes Builder 2024-06-22 10:31:02 +02:00
install-dev.top feat: add development goodies to Qubes Builder 2024-06-22 10:31:02 +02:00
install-qubes-executor.sls refactor: prefer systemd sockets over socat 2024-06-25 22:16:26 +02:00
install-qubes-executor.top refactor: initial commit 2023-11-13 14:33:28 +00:00
install.sls refactor: prefer systemd sockets over socat 2024-06-25 22:16:26 +02:00
install.top refactor: initial commit 2023-11-13 14:33:28 +00:00
prefs.sls fix: shutdown template before install state 2024-06-24 08:38:56 +02:00
prefs.top fix: install salt depends in fedora-39-minimal 2024-03-23 22:09:49 +01:00
README.md doc: lint markdown files 2024-07-04 17:27:31 +02:00
version fix: generate RPM Specs for Qubes Builder V2 2024-06-21 17:00:06 +02:00

qubes-builder

Setup Qubes OS Builder V2 in Qubes OS itself.

Table of Contents

Description

Setup a Builder qube named "qubes-builder" and a disposable template for Qubes Executor named "dvm-qubes-builder". It is possible to use any of the available executors: docker, podman, qubes-executor.

During installation, after cloning the qubes-builderv2 repository, signatures will be verified and the installation will fail if the signatures couldn't be verified. Packages necessary for split operations such as split-gpg2, spit-git and split-ssh-agent will also be installed.

Installation

The template is based on Fedora Minimal and not Debian Minimal due to the Qubes Executor lacking some dependencies on Debian such as mock. Even if the builder qube was Debian based, the executor qube still needs to be a Fedora template.

If installation fails on non existent qubes-infrastructure-mirrors directory during the qubes-builder.configure state, please [manually pull new commits](#Pulling new commits) and then run the state again. This issue will occur to everyone that ran the same state before 2024-07-01, due to submodule addition. Qusal maintainer decision is not to handle such issue automatically as it can lead to data loss in case user does manual changes, the installation would need to reset the user changes and to do a clean pull that wouldn't fail. After you've pulled the commit including the .gitmodules once, future installations won't have this issue.

  • Top:
sudo qubesctl top.enable qubes-builder
sudo qubesctl --targets=tpl-qubes-builder,dvm-qubes-builder,qubes-builder state.apply
sudo qubesctl top.disable qubes-builder
sudo qubesctl state.apply qubes-builder.prefs
  • State:
sudo qubesctl state.apply qubes-builder.create
sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder state.apply qubes-builder.install
sudo qubesctl state.apply qubes-builder.prefs
sudo qubesctl --skip-dom0 --targets=dvm-qubes-builder state.apply qubes-builder.configure-qubes-executor
sudo qubesctl --skip-dom0 --targets=qubes-builder state.apply qubes-builder.configure

If you plan to write for a long time and analyze logs on the builder qube, it is recommended to install some development goodies:

sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder state.apply qubes-builder.install-dev

If you plan on building Qusal packages (Development only):

sudo qubesctl --skip-dom0 --targets=qubes-builder state.apply qubes-builder.configure-qusal

Access Control

The policy is based on qubes-builderv2/rpc/50-qubesbuilder.policy. Extra services added are qubes.Gpg2, qusal.GitInit, qusal.GitFetch, qusal.GitPush, qusal.SshAgent. Necessary services are allowed to have an unattended build.

Usage

Pulling new commits

The installation will clone the repository but not pull new commits. You will need to pull new commits from time to time, their signature will be automatically verified before merging them to your git index.

Pull qubes-builderv2 commits:

git pull

Initialize and merge submodules:

git submodule update --init
git submodule update --merge

Add PGP public key to qubes-builder GPG home directory

If you need to pull commits signed by someone with a key not deployed by default, import their key to the GPG home directory of qubes-builder:

gpg-qubes-builder --import /path/to/key

Builder configuration

When using the Qubes Executor, configure the builder.yml dispvm option to either dom0 or dvm-qubes-builder:

include:
  - example-configs/desired-config.yml

executor:
  type: qubes
  options:
    dispvm: "dom0"
    #dispvm: "dvm-qubes-builder"

gpg-client: gpg

Setting the Disposable VM to Dom0 works because it will use the default_dispvm preference of qubes-builder, which is dvm-qubes-builder.

Setting the gpg-client explicitly to enforce the use of split-gpg2.

Build Qusal

Warning: development only.

You can easily build Qusal as a default configuration is provided.

Place only the following in builder.yml:

include:
  - ../qusal-builder/qusal.yml

To run the sign state, you will need to change the configuration option sign-key:rpm:KEY to your key fingerprint as well as import the same key to the default GnuPG home directory ~/.gnupg.