Update VirtualBox build + extend to ARM64

.github/workflows/build-init.yml

@@ -5,38 +5,56 @@ on:
   push:
     branches: [main]
   pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
     paths-ignore: ["docs/**"]
 jobs:
   build-init:
-    # this job initialises the vagrant box
-    # then just runs some initial ansible tasks
-    # for the full build,  see build.yml
-    runs-on: macos-latest
-    env:
-      VAGRANT_NO_GUI: true
-      VAGRANT_ON_GH: true
+    if: github.event.pull_request.draft == false
+    # this job tests ansible provisioning in Docker containers
+    # Tests on both ARM64 and AMD64 architectures using Ubuntu runners
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm]
 
     steps:
     - uses: actions/checkout@v4
-    - name: set up Python
+
+    - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        python-version: 3.13
 
-    - name: install pip requirements
+    - name: Install pip requirements
       run: |
         pip install --upgrade pip
         pip install wheel
         pip install -r requirements.txt
 
-    - name: install ansible requirements
+    - name: Install Ansible requirements
       run: ansible-galaxy install -r requirements.yml
 
-    - name: Build Vagrant Box
-      run: ANSIBLE_ARGS="--tags init,ci_test" vagrant up
+    - name: Install Docker collection for CI
+      run: ansible-galaxy collection install community.docker
+
+    - name: Start Ubuntu Docker container
+      run: |
+        docker run -d --name quantum-mobile \
+          -v ${{ github.workspace }}:/workspace \
+          ubuntu:24.04 \
+          sleep infinity
+
+    - name: Prepare container for Ansible
+      run: docker exec quantum-mobile bash -c "apt-get update && apt-get install -y python3 sudo"
+
+    - name: Run Ansible provisioning
+      run: ansible-playbook -v --limit docker-ci -e build_hosts=docker-ci --skip-tags ci_skip playbook-build.yml
+      env:
+        ANSIBLE_CALLBACKS_ENABLED: ansible.posix.profile_tasks
 
     - name: Archive ansible log
+      if: always()
       uses: actions/upload-artifact@v4
       with:
-        name: ansible-log
+        name: ansible-log-${{ matrix.os }}
         path: ansible.log

Vagrantfile

@@ -5,8 +5,7 @@ require 'yaml'
 current_dir    = File.dirname(File.expand_path(__FILE__))
 inventory      = YAML.load_file("#{current_dir}/inventory.yml")
 # host specific variables take priority over global ones
-gconfig        = inventory['all']['vars'].merge(inventory['all']['hosts']['vagrant-provision'])
-playbook       = ENV["BUILD_PLAYBOOK"] || "playbook-build.yml"
+gconfig        = inventory['all']['vars']
 launch_gui     = ENV.has_key?('VAGRANT_NO_GUI') ? false : true
 
 # Currently on GitHub Actions it fails if accelerate3d activated
@@ -36,9 +35,9 @@ Vagrant.configure(2) do |config|
      # See https://www.virtualbox.org/manual/ch08.html
      vb.customize ["modifyvm", :id, "--vram", gconfig['vm_vram']]
      # makes mouse/typing more responsive
-     if !(on_ci)
-      vb.customize ["modifyvm", :id, "--accelerate3d", "on"]
-     end
+    #  if !(on_ci)
+    #   vb.customize ["modifyvm", :id, "--accelerate3d", "on"]
+    #  end
      # see https://github.com/marvel-nccr/quantum-mobile/issues/99
      vb.customize ["modifyvm", :id, "--graphicscontroller", "vmsvga"]
      vb.customize ["modifyvm", :id, "--clipboard", "bidirectional"]
@@ -79,20 +78,6 @@ Vagrant.configure(2) do |config|
   # Disable the default shared folder of vagrant
   config.vm.synced_folder ".", "/vagrant", disabled: true
 
-  # provisioner: set up VM via ansible. To (re-)run this step:
-  #   vagrant provision --provision-with ansible
-  # Note we use a static inventory, see: https://www.vagrantup.com/docs/provisioning/ansible_intro#static-inventory
-  config.vm.network :private_network, ip: gconfig["ansible_host"]
-  config.vm.provision "ansible" do |ansible|
-    ansible.inventory_path = "inventory.yml"
-    ansible.limit = "vagrant-provision"
-    ansible.playbook = playbook
-    # ansible.verbose = "v"
-    ansible.extra_vars = {
-      build_hosts: "vagrant-provision",
-    }
-    ansible.raw_arguments = Shellwords.shellsplit(ENV['ANSIBLE_ARGS']) if ENV['ANSIBLE_ARGS']
-    # Ensure that public key auth is not disabled by the user's config
-    ansible.raw_ssh_args = ['-o PubKeyAuthentication=yes -o DSAAuthentication=yes']
-  end
+  # Note: provisioning is done separately via `tox -e ansible`, which first
+  # generates the vagrant-ssh config file and then runs the playbook.
 end

ansible.cfg

@@ -10,19 +10,24 @@ roles_path = ./submodules/roles
 
 # workaround for https://github.com/ansible/ansible/issues/14426
 timeout = 30
+# Temporarily allow broken conditionals until collections are updated for Ansible 13
+allow_broken_conditionals = True
 
-# Use the YAML callback plugin.
-stdout_callback = yaml
+# Use the default callback plugin with YAML output format.
+stdout_callback = ansible.builtin.default
 # Use the stdout_callback when running ad-hoc commands.
 bin_ansible_callbacks = True
 
+[ansible.builtin.default]
+result_format = yaml
+
 # when changing user via su, this opens a login shell
 # (i.e. executes .profile)
 # See https://askubuntu.com/a/376386/715125
 ansible_su_flags = "- "
 
 # provide execution time during run
-callback_whitelist = profile_tasks
+callbacks_enabled = ansible.posix.profile_tasks
 
 [ssh_connection]
 # reduces the number of SSH operations required to execute a module

docs/developers/build-vagrant.md

@@ -2,44 +2,26 @@
 
 In the following, we explain how to build your own custom Quantum Mobile VirtualBox image from scratch.
 
-Calculate at around two hours for building the full VM:
+Note that building the full VM can take around 15 minutes.
 
-````{dropdown} Approximate Timings
-```
-marvel-nccr.bigdft : Compile bigdft executables ----------------------- 906.73s
-marvel-nccr.quantum_espresso : Make QE executables -------------------- 867.71s
-marvel-nccr.abinit : Make abinit executable (2 cpu) ------------------- 807.30s
-marvel-nccr.wannier90 : run Wannier90 default tests ------------------- 720.07s
-marvel-nccr.libxc : Compile libxc executable (2 cpu) ------------------ 678.97s
-marvel-nccr.ubuntu_desktop : Install ubuntu-desktop (apt) ------------- 532.78s
-marvel-nccr.yambo : Make Yambo executables ---------------------------- 406.67s
-marvel-nccr.fleur : run fleur tests ----------------------------------- 395.95s
-marvel-nccr.fleur : Make fleur executables ---------------------------- 345.77s
-marvel-nccr.abinit : run the tests (2 cpu) ---------------------------- 315.32s
-marvel-nccr.libxc : Run make check for libxc -------------------------- 313.18s
-marvel-nccr.siesta : Make siesta executable --------------------------- 308.16s
-marvel-nccr.aiida : Install aiida-core + plugins into venv ------------ 262.80s
-marvel-nccr.slurm : Install apt packages ------------------------------ 211.29s
-marvel-nccr.simulationbase : Install plotting tools, etc. ------------- 187.73s
-marvel-nccr.siesta : Make xmlf90 -------------------------------------- 179.07s
-marvel-nccr.bigdft : run test suite ----------------------------------- 143.86s
-marvel-nccr.aiidalab : install server-side (aiida) dependencies ------- 120.63s
-marvel-nccr.cp2k : download cp2k binary ------------------------------- 108.26s
-marvel-nccr.ansible_prerequisites : Install aptitude ------------------ 104.13s
-```
-:::{seealso}
-See the [continuous deployment (CD) workflow](https://github.com/marvel-nccr/quantum-mobile/actions?query=workflow%3ACD) for up-to-date timings
-:::
-````
 
 ## Prerequisites & Installation
 
-- Operating system: Building Quantum Mobile has been tested on MacOS, Ubuntu and Windows.
-- [Vagrant](https://www.vagrantup.com/downloads.html) >= 2.0.1
-- [VirtualBox](https://www.virtualbox.org/wiki/Downloads) >= 6.1.6
-- [Python](https://www.python.org/) >= 3.6
+Building Quantum Mobile requires and has been tested on:
+
+- Operating system: MacOS Sequoia 15.5 and Ubuntu 24.04.
+- [Vagrant](https://www.vagrantup.com/downloads.html) 2.4.9
+- [VirtualBox](https://www.virtualbox.org/wiki/Downloads) 7.2.6
+- [Python](https://www.python.org/) 3.13
+
+But may also work for more recent versions.
 
 ````{dropdown} Building on Windows
+
+:::{warning}
+This has not been tested in some time, here be dragons. 🐉
+:::
+
 - Install [Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)
 - Install VirtualBox under *Windows*
 - Add the following lines to your `.bashrc` in WSL:
@@ -59,59 +41,46 @@ git clone https://github.com/marvel-nccr/quantum-mobile.git
 cd quantum-mobile
 ```
 
-Install [tox](https://tox.readthedocs.io/) and the `vagrant-vbguest` plugin:
+Install [tox](https://tox.readthedocs.io/):
 
 ```bash
 pip install tox
-# improves interface
-vagrant plugin install vagrant-vbguest
 ```
-:::{tip}
-For those using [Conda](https://docs.conda.io/), it is recommended to also install [tox-conda](https://github.com/tox-dev/tox-conda):
-
-```bash
-pip install tox-conda
-```
-
-:::
 
 ## Create the Virtual Machine
 
-:::{seealso}
-If you would like to [customise](customize.md) any aspects of the VM, now would be a good time to do so.
-:::
-
-
-Use [tox](https://tox.readthedocs.io/) to set up the Python environment and run the build steps.
+We use [tox](https://tox.readthedocs.io/) to set up the Python environment and run the build steps.
 
 ```bash
-tox -a -v        # shows available automations
-tox -e vagrant
+tox -e vagrant      # create and start the VM
+tox -e ansible      # provision the VM with Ansible
 ```
-This will call `vagrant up`, to initialise the VM, which then calls `ansible-playbook playbook-build.yml`, to configure the VM and build the required software on it.
 
-:::{tip}
-If you get an error during the installation of the VirtualBox Guest Additions, you may need to perform additional steps (see [issue #60](https://github.com/marvel-nccr/quantum-mobile/issues/60)).
-:::
-:::{tip}
-Building the Desktop Edition is tested on GitHub Actions on every commit to the repository.
-For the tested steps see the `.github/workflows/build.yml` file.
-:::
+This will:
+1. `tox -e vagrant`: Call `vagrant up` to create and start the VM
+2. `tox -e ansible`: Generate the SSH configuration file (`vagrant-ssh`) and call `ansible-playbook playbook-build.yml` to provision the VM and build the required software on it
+
+You can see all available `tox` environments with:
 
+```bash
+tox -a -v           # shows available automations
+```
 
 ### Continuing a failed build
 
 If the build fails or is interrupted at any step (for example a failed download, due to a bad connection),
 you can continue the build with:
 
 ```bash
-# output the vagrant box connection details
-vagrant ssh-config > vagrant-ssh
 tox -e ansible
 ```
 
 The ansible automation steps are generally idempotent, meaning that if they have been previously run successfully, then they will be skipped in any subsequent runs.
 
+:::{note}
+You don't need to manually run `vagrant ssh-config > vagrant-ssh` - `tox -e ansible` does this automatically.
+:::
+
 ### Running only selected steps
 
 All steps of the ansible build process are "tagged", which allows you to select to run only certain steps, or skip others.
@@ -124,19 +93,13 @@ tox -e ansible -- --list-tags
 
 or look at `playbook-build.yml`.
 
-To run only certain tags, use either:
-
-```bash
-ANSIBLE_ARGS="--tags tag1,tag2 --skip-tags tag3" tox -e vagrant
-```
-
-or
+To run only certain tags, use:
 
 ```bash
 tox -e ansible -- --tags tag1,tag2 --skip-tags tag3
 ```
 
-## Creating the image
+### Creating the image
 
 First, clean unnecessary build files:
 
@@ -156,10 +119,38 @@ This will compact the hard disk of the virtual machine and export the image and
 The `validate` tag checks that the repositories git tag is the same as the `vm_version` specified in `inventory.yml`, and is only needed for new releases by Quantum Mobile maintainers.
 :::
 
-## Other Useful commands
+### Other Useful commands
 
 - `vagrant reload`: restart machine
 - `vagrant halt`: stop machine
 
 Vagrant keeps information on how to connect in a folder called `.vagrant`.
 If you would like to create a new machine, `vagrant destroy` will remove the `.vagrant` folder and allow you to create a new VM (note: you may want to keep a copy in case you want to reconnect later).
+
+## Troubleshooting
+
+### VirtualBox Guest Additions Issues
+
+If you experience issues with shared folders, clipboard sharing, or graphics performance, you may need to manage VirtualBox Guest Additions manually.
+Install the `vagrant-vbguest` plugin:
+
+```bash
+vagrant plugin install vagrant-vbguest
+```
+
+Then you can:
+
+```bash
+# Check Guest Additions status
+vagrant vbguest --status
+
+# Manually install/update Guest Additions
+vagrant vbguest --do install
+
+# Rebuild Guest Additions
+vagrant vbguest --do rebuild
+```
+
+:::{note}
+VirtualBox Guest Additions are tools that run inside the VM to provide features like shared folders, seamless mouse integration, and better graphics. The base Ubuntu box comes with Guest Additions pre-installed, but version mismatches can occur when you upgrade VirtualBox, potentially causing shared folder or clipboard issues. This plugin helps resolve such mismatches.
+:::

docs/maintainers/develop.md

@@ -15,13 +15,16 @@ pre-commit run --all
 pip install tox
 # to build from scratch
 tox -e docs-clean
+# to update the build (faster, doesn't remove existing build)
+tox -e docs-update
 # to start a live server (reloads automatically on changes to documentation)
 tox -e docs-live
 ```
 
 ## Testing a build on GH Actions
 
-Pushing a commit to master or a PR on GitHub will trigger a pre-commit and initial build (only for `init` tagged tasks) tests on GH Actions.
+Pushing a commit to main or a PR on GitHub will trigger a pre-commit test and a Docker-based build test on GitHub Actions.
+The build test runs Ansible provisioning in Docker containers on both ARM64 (`ubuntu-24.04-arm`) and AMD64 (`ubuntu-latest`) architectures.
 
 You can also trigger a full build test of either the vagrant or docker builds, by pushing a git tag prefixed `vagrant-` or `docker-`.
 

docs/maintainers/release.md

@@ -4,7 +4,7 @@
 
 * [Vagrant](https://www.vagrantup.com/downloads.html)
 * Vagrant [vbguest plugin](https://github.com/dotless-de/vagrant-vbguest) (`vagrant plugin update`)
-* [bento/ubuntu-18.04](https://app.vagrantup.com/bento/boxes/ubuntu-18.04) Vagrant image (`vagrant box update`)
+* [bento/ubuntu-24.04](https://app.vagrantup.com/bento/boxes/ubuntu-24.04) Vagrant image (`vagrant box update`)
 * [Virtual Box](https://www.virtualbox.org/wiki/Downloads)
 * QM codes
   * [Quantum Espresso](https://gitlab.com/QEF/q-e/tags)
@@ -60,28 +60,13 @@ tox -e update-vagrant
 
 Follow the [desktop build instructions](../developers/build-vagrant.md).
 
-:::{note}
-Manual modifications required, as of QM 23.04.01, desktop shortcuts mut be manually enabled:
-
-- First install the file with <https://manpages.ubuntu.com/manpages/focal/en/man1/desktop-file-edit.1.html>:
-
-  ```console
-  $ sudo desktop-file-install --delete-original ~/Desktop/homepage.desktop
-  $ sudo desktop-file-install --delete-original ~/Desktop/jupyterlab.desktop
-  ```
-
-- Now navigate to the `/usr/share/applications` in the folder app, find the files and drag/drop them to the Desktop
-- Right click on the file on the Desktop and select `Allow Launching`
-
-:::
-
 ### Cloud Edition
 
 Follow the [cloud build instructions](../developers/build-cloud.md).
 
 * For the server to build the VM, choose e.g. 2 CPUs with 4GB of RAM, with at least 16GB of storage.
   * Your configuration may also be the standard configuration shown to users creating a VM using your image
-  * Currently Ubuntu Server 20.04 LTS
+  * Currently Ubuntu Server 24.04 LTS
   * Expose ports as listed in instructions
   * You won't need it for long, so price for CPU/RAM is of no concern
 * Exemplary metadata: