path: root/wiki/src/contribute/build/vagrant-setup.mdwn
diff options
Diffstat (limited to 'wiki/src/contribute/build/vagrant-setup.mdwn')
1 files changed, 48 insertions, 49 deletions
diff --git a/wiki/src/contribute/build/vagrant-setup.mdwn b/wiki/src/contribute/build/vagrant-setup.mdwn
index 34dc271..9d89107 100644
--- a/wiki/src/contribute/build/vagrant-setup.mdwn
+++ b/wiki/src/contribute/build/vagrant-setup.mdwn
@@ -8,6 +8,8 @@ upload the template virtual machine.
+[[!toc levels=2]]
@@ -21,75 +23,72 @@ This directory contains:
run inside the virtual machine upon boot,
* `provision/assets/build-tails`: build script to be run inside the
virtual machine,
- * for building the base box:
+ * to build the base box:
- `definitions/tails-builder/`: Script
- that generates the base box. The box naming format and disk size
- is specified in this script, as well as the vmdebootstrap
- parameters (Debian distribution, architecture, etc).
+ that generates the base box.
- `definitions/tails-builder/`: Script that is run
inside the base box before finalizing it, e.g. for installing the
packages we need.
+ - `vagrant/lib/tails_build_settings.rb` defines the basebox properties
+ (memory, Debian version, architecture, ...) and the basebox name.
We choose to use the [Shell
provisioner](, as long as we
make this script reentrant it will lower the learning curve for contributors
not familiar with Puppet or Chef.
-The Vagrantfile will share the `.git` directory of the local clone of the
-repository. This is done to overcome limitations of VirtualBox shared folders
-(namely *symlink support*). The build script will clone (and fetch further
-changes) that "bare" repository.
-Creating the base box
-The creation of the base box is fully automated using `vmdebootstrap`
-and `vagrant-libvirt`'s `` script.
-Installing the requirements
+The Tails [[!tails_gitweb vagrant/Vagrantfile desc="Vagrantfile"]] is
+configured to share the local clone of the Tails repository inside the running
+basebox through a 9pfs mount.
-Debian packages:
+Automated basebox creation
- sudo apt install vmdebootstrap vagrant-libvirt
+While implementing [[reproducible builds|blueprint/reproducible_builds]] of
+Tails, we choose to automate the basebox creation. Rather than downloading a
+big binary, everyone building Tails for the first time will start by generating
+the approriate basebox if it's not already available locally.
-Generating a new base box
+To ensure that the baseboxes are identical enough, we defined a mechanism for
+its generation:
-Until [[!debbug 823317]] is solved, the `vagrant-libvirt` package in
-Debian is missing a script we depend on, so you have to copy
-to `/usr/share/vagrant-plugins/vagrant-libvirt/tools/`
-before attempting the following!
+To freeze the build environment, we use APT snapshots in the same way we do in
+the Tails build system, by storing the serials for the various APT repositories
+in [[!tails_gitweb_dir
-If needed, modify `vagrant/definitions/tails-builder` (e.g. if new
-packages are required, add them through ``), and commit
-the changes. Then simply run:
+Only the debian-security APT source uses Debian's APT repository, so that we
+get security fixes. This will probably not influence the reproducibility of the
+ISO. This is done in the [[!tails_gitweb vagrant/provision/setup-tails-builder
+desc="Vagrant provisioning script"]].
- rake basebox:create
+To ensure that changes in the Vagrant build system are still taken into account
+when using a basebox, we dynamically set the name of the basebox by including
+the short ID of the last commit in the `vagrant` directory in the related
+branch, as well as its date, in the name of the basebox. That's done with
+[[!tails_gitweb_dir vagrant/lib/tails_build_settings.rb]] as explained above.
-Note that it will require you to be a `sudo`er and will ask you for
-your password.
+We update the basebox APT snapshots serials [[at every Tails
-Make Tails build with the new base box
+A new VM is created from the basebox for each build. After the build, the VM is
+destroyed ([[!tails_ticket 11980]] and [[!tails_ticket 11981]]).
-Let's assume it's the most recent `.box` file in the current directory
-(which will be the case after generating a new base box), otherwise
-set `BOX` appropriately below:
+The `keeprunning` build option can be used so that the VM is kept running and
+reused for subsequent builds of the same branch.
- BOX="$(ls -1tr vagrant/definitions/tails-builder/*.box | tail -n1)"
- BOX_NAME="$(basename "${BOX}" .box)"
- BOX_CHECKSUM="$(sha256sum "${BOX}" | cut -f 1 -d ' ' | tr -d '\n')"
- sed -i \
- -e "s/^\(\s*\s*=\s*\).*$/\1'${BOX_NAME}'/" \
- -e "s/^\(\s*config.vm.box_download_checksum\s*=\s*\).*$/\1'${BOX_CHECKSUM}'/" \
- vagrant/Vagrantfile
- git commit -m "Upgrade Vagrant base box to '${BOX_NAME}'." vagrant/Vagrantfile
+The VM encodes (in `/var/lib/vagrant_box_build_from`) the branch for which it
+has been started for. The ISO build aborts if the branch being built is not the
+same as the one that is encoded in this file. This prevents the reuse of a
+running VM to build another branch than the one it has been started for
-If you want to use this base box locally, just add it with
+To ensure that the `apt-cacher-ng` cache is not lost when the VM is destroyed,
+it is stored in a dedicated virtual disk, and plugged into every new build VM.
- vagrant box add "${BOX}"
-If this base box is to be available from our mirrors, please upload it
-to the `project/vagrant` directory of our rsync server.
+All these features and the [[basic ones|contribute/build]] are used by our
+Jenkins ISO builders. See [[here for