Vagrant files to prepare a Virtual Machine image for preCICE, mainly for demo and teaching purposes.
Vagrant pulls an Ubuntu 20.04 "base box" and asks e.g. VirtualBox to start a virtual machine. It then installs basic tools (such as a desktop environment), a preCICE release, several solvers and adapters, as well as example and tutorial files.
Ready-to-use boxes are available on Vagrant Cloud.
Note: If you only want to directly get a pre-built box, look at the documentation.
vagrant up
.vagrant reload
to get a full GUIYou can afterwards also see and manage the produced VM in VirtualBox.
A few things you may need:
vagrant
/vagrant
install-basics.sh
or through the keyboard setting shortcut on ~/Desktop
.~/Desktop/shared
.vagrant suspend
, vagrant resume
vagrant halt
, vagrant destroy
vagrant provision
vagrant ssh
vagrant package --base "preCICE-VM" --output preCICE.box
vb.cpus
and vb.memory
in the Vagrantfile
./vagrant/
directory reflects the directory of the Vagrantfile
.This box is based on the generic/ubuntu2004 bento/ubuntu-20.04 base box and installs:
Applications > System
)It then adds to the /home/vagrant/
:
precice/tutorials
The adapter repositories remain in /home/vagrant/
.
It also adds a few shortcuts on the Desktop (see post-install.sh
).
At the end, it cleans up all object files and the APT cache (see cleanup.sh
).
Even though most hardware supports virtualization, your CPU may not or you may need to enable it in your BIOS/UEFI settings.
The most common reason can be that one of the third-party APT repositories
(such as the repository of OpenFOAM on SourceForge) do not respond.
Usually running again (e.g. with vagrant up --provision
) helps.
In case you killed the session before provisioning finished, the setup of your VM might be incomplete. You might still be able to interact with the VM without the GUI. In that case, run vagrant up --provision
.
We now have a GitHub action that can build the Vagrant box. This workflow only runs for pull requests that are marked as "ready for review" (i.e. not "draft"), as it takes significant time to complete (~1.5h). If you already submitted a normal PR but the workflow is not triggered, you can manually trigger it from the "Actions" tab.
The workflow uploads the resulting box as an artifact and it also prints its SHA256 checksum before that. Download the job artifact and unzip it. Then run add the box to Vagrant:
vagrant box add test-box precice-vagrant-box/preCICE.box
You can then start a VM by going into an empty directory and executing:
vagrant init test-box
vagrant up
Afterwards, you probably want to destroy everything to save storage space:
vagrant destroy
vagrant box remove test-box
If you require a more responsive experience, lower overhead, or exotic features such as GPU pass through, then the libvirt
vagrant box is for you.
This allows you to run the vagrant box via libvirt and QEMU as a Kernerl Virtual Machine (KVM).
Note The libvirt variant does not work with the
bento/ubuntu-20.04
base image, but also the VirtualBox variant does not at the moment work with thegeneric/ubuntu2004
image. Change the base image in the beginning of the Vagrantfile if you need this feature. See https://github.com/precice/vm/issues/83 for details.
To use this box, first install the vagrant plugin vagrant-libvirt
following the official installation instructions.
Then you follow the normal usage instructions above, but you need to tell vagrant to use the libvirt
box by passing one additional option:
vagrant up --provider=libvirt