Projects tester using VBox VM

Tue 2026/07/21 Maintenance project / management / virtualbox

Overview

• repo status: Repo Information
• installation: Common Setup

Summary

I have many repos that I need to maintain. Part of that is to double-check that it installs correctly and runs, unit tests and if possible verifies correctly.

To do that, I create a minimal Virtualbox VM and then create the repos one-by-one. I run the scripts in each one as appropriate and track any significant failures. see Repo Information for the current status.

The VM allows me to reset the machine to a minimal state. Therefore I can check if the project has all the necessary.

Currently, I only run this VM for Ubuntu. I do run the same tests on macOS and MSYS2/Windows but I don't have a method to reset these systems to a minimal state.

Assumptions

I do have some assumptions that are needed by my development setup. That means you can use these scripts and instructions as starting point but you may have to modify for your individual development process.

• ~/.pypirc : if you publish to pypi.org
• ~/projects/cpip : sym link to NAS directory for holding various files
• userid group dialout: needed for USB/UART interactions
• add other SSH keys you need the VM to have access to
• add other tools/languages you need at the global level
• add other apps/tools you don't need and can be cleaned up
• any other global files, config files, etc. should be added to proj-tester

Run it - top level

• update proj-tester/pt-common-data for your userid, etc. Copy proj-tester/sample-pt-common-data as a starting point.
• update proj-tester/pt-project-clone to select a project to clone. Copy proj-tester/sample-pt-project-clone as a starting point.
• update proj-tester/pt-project-run-steps to test the project. Copy proj-tester/sample-pt-project-run-steps as a starting point.
• if you have additional ssh keys add them using pt-check-ssh-more-keys. Use proj-tester/sample-pt-check-ssh-more-keys as a starting point.
• double check the rest of the scripts and files in proj-tester for your system
• Follow instructions in doc/host-to-vm-projtester.md or see the webpage at proj-man-tester
• Test all the projects you have in the VM

How to create a VM Project Tester

Steps on how to install and configure Ubuntu Server 24.04 running on a VirtualBox VM ("virtual machine").

• host: is the PC that runs VirtualBox (vbox).
• guest: is the VM that is running in vbox.

Note I run VirtualBox ("vbox") on my host PC which is running Ubuntu 24.04. But running vbox should work correctly on Windows or macOS.

Also see Ubuntu Desktop on vbox

Install the latest vbox:

sudo apt install virtualbox-7.2

preparation

guest info

• choose a username for your guest account: e.g. guest_userid
• choose a password for your guest account: e.g. guest_password
• choose a name for the guest VM: guest_name (vm-02 in this doc)

ip addresses

• choose an IP address for your guest VM: e.g. 10.0.0.15
• know the IP address on your development PC: e.g. 10.0.0.xx
• know the hostname of your development PC: john26
• know the other hostnames listed in your /etc/hosts e.g. "john29" (my common NAS server)

shared directory

• a directory name to share e.g. "vm-shared"
• choose a directory on your host PC for the shared directory e.g. /home/host_userid/vm-shared
• choose a directory on the guest VM for the shared directory e.g. /home/guest_userid/vm-shared
• you can have different names, but it is much easier to remember the same name on both host and guest.

ethernet access

• I assumed that you may want to connect to the VM from multiple PC's on your local internet e.g. on a second PC.
• I also assumed you can assign a fixed IP address to the VM via your router e.g. 10.0.0.15

check virtualbox installation

On Host:

• Download the Desktop version you wish to install.
  • goto Alternative Downloads
  • select Past Releases
  • click on "Ubuntu 24.04.4 LTS Noble Numbat"
  • takes about 6m to download
• Remove previous versions of vbox:
  • run dpkg -l | grep -i virtualbox to get the current virtualbox installed
  • run sudo apt remove virtualbox7.2 or the version you have installed
• Download vbox for Ubuntu 24.04
  • Go to VirtualBox Downloads
  • download v7.2.12 deb file
  • run dkpg -i virtualbox-7.2_7.2.12-174389~Ubuntu~noble_amd64.deb or click on the .deb file to install it
• Download matching GuestAdditions:
  • Go to GuestAdditions Downloads
  • select 7.2.12
  • select VBoxGuestAdditions_7.2.12.iso
• For using USB in VM:
  • Go to VirtualBox Downloads
  • Download the "VirtualBox Extension Pack" that matches your exact VirtualBox version.
  • double-click the .ext-pack file and install it
  • on Host (not guest!) sudo usermod -aG vboxusers $USER

create VM

• open vbox v7.2.12
  • click Machine
  • click New
    • name: guest_name (e.g. vm-02-proj-tester)
    • Folder: should default to your normal VM directory
    • ISO image: select the file .iso file you downloaded e.g. ~/Downloads/ubuntu-24.04.4-desktop-amd64.iso
    • unselect "Proceed with Unattended installation"
    • click "Specify Virtual Hardware"
  • get Hardware
    • Base Memory: select 10240 MB
    • Processors: 1 CPU
    • Enable EFI: leave unchecked
    • click "Specify virtual Hard Disk"
  • get Hard disk
    • select Create a Virtual Hard Disk Now
    • Hard Disk File Location and Size: select 60 GB (minimum)
    • select VDI (VirtualBox Disk Image), leave Pre-allocate Full Size unchecked
    • click Finish
• Click settings
  • System:
    • deselect Floppy (select: optical and HD only)
  • Network:
    • Attached to: Bridged Adapter
    • Name enp89s0
    • Mac: 080027791603 (record the MAC address so that your VM will get the same IP address from your router)

initial Ubuntu installation

vbox VM is now created, but Guest Ubuntu is not installed

• select the VM, click Start
• put mouse in VM box
• Should show Grub boot terminal. "Try or Install Ubuntu" press Enter
• get Desktop screen
• get "Welcome to Ubuntu" dlgbox
• Choose your language: select English (or your language), click Next
• Accessibility in Ubuntu: leave as is (or any if you need them), click Next
• Select your keyboard layout: select English (US), click Next
• Connect to the internet: select "Use wired connection"
• Update available: click Update now
• Update ready: click close Installer
• click on icon (lower right of screen) "Install Ubuntu 24.04.4 LTS"
• get "Welcome to Ubuntu" dlgbox again
• repeat the above until: "How would you like to install Ubuntu?"
• select "Interactive installation", click Next
• select "Default Selection", click Next
• Install recommended proprietary software?
  • select Install third-party software
  • select download and install support for additional media formats
  • click Next
• How do you want to install Ubuntu
  • select erase disk and install Ubuntu
  • Advanced features: None Selected
  • click Next
• Create your account
  • Your name: guest_userid
  • Your computer's name: vm-02 (i.e. the hostname)
  • your username: guest_userid
  • require my password to log in: selected
  • click Next
• select your timezone: click Next
• Review our choices: click Install
• installation starts

initial setup of Ubuntu on VM

Installation process should take around 8 minutes

• get "...installed and ready to use", click "Restart Now"
• get "Please remove the installation medium"
  • click Devices
  • click Optical Drive
  • ensure .iso is not selected
  • click on desktop screen
  • press Enter
• system reboots; wait <1m...
• should see a login screen
• login with the userid and password you entered
• dlgbox "Welcome to ...", click Next
• "Ubuntu Pro", click Skip
• "Help Improve Ubuntu", select "No don't share system data", "click Next"
• "Get started ...", click "Finish"
• unpin Help
• open settings, pin to dash
• click "Appearance", choose a different Background to differentiate from your host OS background
• click "Ubuntu Desktop", set icon size to 32
• close settings
• Open Terminal, pin to dash
• enter stty sane

update settings for the VM

• Power off Guest Ubuntu (i.e. not VM power off!)
  • click on power switch icon
  • click on "Power Off..."
  • get dlgbox, click on "Power Off"
• in vbox Manager, right click on the VM
• click Settings
  • General: (double check)
    • Features:
      • shared clipboard: Bidirectional
      • Drag'n'Drop: Disabled
    • other defaults are ok
  • System: (double check)
    • deselect "Floppy" in "Boot Order"
    • other defaults are ok
  • Display: defaults are ok
  • Storage:
    • in "Controller: IDE", select "Empty"
    • click blue disk icon
    • select VBoxGuestAdditions_7.2.12.iso, or if not present, select "Choose a disk file" and navigate to ~/Downloads, select VBoxGuestAdditions_7.2.12.iso
    • defaults are ok
  • Audio: defaults are ok
  • Network
    • Adapter 1:
      • Attached to: Bridged Adapter
      • Name: enp89s0 (may be different)
      • MAC address: update to use the previous value (080027791603) used in your router, or accept the current one
      • Virtual Cable connected: selected
  • Serial Ports: defaults are ok
  • USB:
    • select USB 3.0
    • other defaults are ok
  • Shared Folders:
    • on host: open a terminal; mkdir -p ~/vm-shared
    • in VM settings: click Blue Folder+ icon
      • Folder Path:
        • right menu: select Other and then locate and select /home/$host_userid/vm-shared (note: this is on the host)
      • Folder Name: vm-shared
      • Mount-point: /home/$guest_userid/vm-shared (this path is on the guest)
      • click Auto-mount
      • click Ok
  • User Interface: defaults are ok
• click OK

Initial Ubuntu setup

• Start VM and login
• Note: if you get the update software dlgbox, close it, going to do that below.
• open a terminal

# guest:
ip address
# should be the expected IP address from your router e.g. 10.0.0.15

# needed for SSH
sudo apt install -y openssh-server

• check your host can communicate with it

# host:

ping 10.0.0.15
# assumes vm-02 is in /etc/hosts on
ping vm-02 

• set up an SSH key to your VM

# host:
# generate the key
ssh-keygen -t ed25519 -C "your_email@example.com"

# send the key to the VM; you will have to enter your password
ssh-copy-id -i ~/.ssh/vm-02-ed25519.pub vm-02

# add an entry in .ssh/config
Host vm-02
   HostName 10.0.0.15
   User guest-userid
   Port 22
   IdentityFile /home/guest-userid/.ssh/vm-02-ed25519
   IdentitiesOnly yes

# check you have the SSH set up
ssh vm-02
# should not ask for a password

SNAPSHOT 1 - basic Ubuntu without any additional packages

At this point, the following are working:

• basic Ubuntu
• VM settings
• setup SSH connection
• Take a snapshot:
  • shutdown the VM window using vbox Power Off
  • click Snapshot
  • click "Take..."
  • enter "base-os v1" for Snapshot Name
  • use the list above for the Description
  • click OK

Note: I use this to redo and recheck installation instructions

install basic components

• Start VM and login
• clone proj-man-tester This repo contains a set a helper scripts that will install basic Ubuntu components.
• send helper scripts to VM

# host:
cd ~/projects/web/maint/proj-man-tester
# or wherever you downloaded it from BitBucket

# nano do-pt-publish and uncomment this line
./proj-tester/host-send-files

• run do-pt-publish to send helper scripts to VM

# host:
./do-pt-publish
# output should be a list of pt-xx files

• on the VM guest, open a terminal

# guest:
# check the proj-tester BIN_DIR directory
ls ~/pt-bin
# should be a full set of pt-* scripts

nano .bashrc
# add this line:
export PATH=$PATH:$HOME/pt-bin

• reopen the terminal or source .bashrc to pick up the change

# test:
pt-report
# should see something like:
   OK  : on VM: 'vm-02'
-------: VM_HOSTNAME   = vm-02
-------: VM_USERID     = guest_userid
-------: HOST_HOSTNAME = john26
-------: BIN_DIR       = /home/guest_userid/pt-bin
-------: python path   = @@ get an error here that python command is not found @@
-------: python path   = @@ is blank @@
    inet 10.0.0.15/24 brd 10.0.0.255 scope global noprefixroute enp0s3
   OK  : rc=0: 
PING google.com (142.250.73.110) 56(84) bytes of data.
64 bytes from pnseaa-an-in-f14.1e100.net (142.250.73.110): icmp_seq=1 ttl=118 time=20.1 ms
64 bytes from pnseaa-an-in-f14.1e100.net (142.250.73.110): icmp_seq=2 ttl=118 time=19.4 ms

--- google.com ping statistics ---
2 packets transmitted, 2 received, 0% packet loss, time 1002ms
rtt min/avg/max/mdev = 19.360/19.740/20.121/0.380 ms
   OK  : rc=0: 

• if it failed to connect to ethernet (could not ping google.com):
  • click Devices | Network | Connect Network Adapter
  • repeat: click Devices | Network | Connect Network Adapter
• add the reported IP address to the router DHCP list

check Guest Additions

• check Devices | Optical Drive | VBoxGuestAdditions is NOT selected
• if it's selected, click on "Remove Disk from Virtual Drive" to remove it
• run guest additions step 1

# guest
pt-guest-additions1
# will automatically powerdown

• restart the VM, login
• start a new terminal
• check Devices | Optical Drive | VBoxGuestAdditions is selected
• if not selected, click on Devices | Insert Guest Additions CD Image
• click on "VBoxGuestAdditions_7.2.12.iso" to add it
• run guest additions step 2

# guest
ls /media/guest_userid
# check there is only one(!) VBox_GAs_7.2.12 file

pt-guest-additions2
# will automatically reboot

check cut-n-paste integration

• login and start a new terminal

# on Host:
# select this text:
pt-report

# on Guest:
# paste it in the terminal

• if it doesn't work
  • re-install build-essential and virtual-guest-utils (in that order)
  • power off and power on the VM

do additional setup

# guest:
# add and confirm vboxsf is a group
# add and confirm bashrc has the PS1 line
pt-check-groups
# the PS1 line will be automatically added, so run it again to double-check
pt-check-groups

# check it worked
source .bashrc
# the prompt should go red; this indicates you are in the Guest VM

check vm-shared permissions

# guest:
ls -al vm-shared
<snip>
drwxrwx---  1 root    vboxsf  4096 Nov  8 20:58 .
drwxr-x--- 17 guest_userid guest_userid 4096 Nov  8 21:17 ..
# there may be additional files here
# the key is the "vboxsf" group

check shared folder

# host:
echo from host > ~/vm-shared/host.txt

# guest:
ls ~/vm-shared
# should see host.txt
cat ~/vm-shared/host.txt

# if fails, on guest: check Devices | Shared Folders | Shared Folder Settings
# ensure Auto-mount is selected; click OK
# then in the guest terminal "sudo mount -a"

# check the other direction
# guest:
echo from guest > ~/vm-shared/guest.txt
# host:
ls ~/vm-shared
# should see guest.txt
cat ~/vm-shared/guest.txt
# should see guest.txt with content "from guest"

• remove the GuestAdditions Disk:
  • in vbox Manager, select the VM
  • click on Settings
  • scroll to Storage
  • select Controller: IDE with the GuestAdditions.iso in it
  • click on the blue disk icon
  • click on "Remove Disk from Virtual Drive"
• check it's gone

# guest
ls /media/guest_userid
# check there is nothing mounted

SNAPSHOT 2 - has git, SSH access bitbucket etc

At this point, the following are working:

• guest additions
• mouse integration
• shared folders
• USB working
• Take a snapshot:
  • click Machine
  • click "Take+" icon
  • enter "base-os v2" for Snapshot Name
  • use the list above for the Description
  • click OK

Install git, access to Bitbucket

• if needed, restart Guest VM and login
• start a terminal

update /etc/host on guest and host

# host:
sudo nano /etc/hosts
# check entry for vm-02
# 10.0.0.15  vm-02         # (wired)  VM for proj-tester
# copy the entries for your servers etc.

# guest:
sudo nano /etc/hosts
# paste 
# NOTE: cut-n-paste in nano may get line numbers
# you may have to manually delete the line numbers in the pasted lines 

# comment out vm-02 entry 
# 10.0.0.15  vm-02         # (wired)  VM for proj-tester
# uncomment out the Host entry
# 10.0.0.xx  your-host     # (wired)  dev PC

• test ip addresses

# guest:
pt-check-hosts
# will ping google, host machine (your-hostname) and common server (if any)

• send over other ssh keys as needed

# host:
cd "proj-man-tester/directory"
./proj-tester/host-send-keys 

• check they worked

# guest:
pt-check-ssh-keys
# should see
 OK  : on VM: 'vm-02'
 OK  : file exists : '/home/guest_userid/.ssh/config'
# the bitbucket key will be missing

set up git and bitbucket access to clone a project

# do once: set up ssh key
# see https://support.atlassian.com/bitbucket-cloud/docs/set-up-personal-ssh-keys-on-linux/
pt-create-bb
# cut-n-paste the key into your bitbucket account
# if this already exists; delete the old one

• add this to .ssh/config

# guest:

nano .ssh/config
# OK - login to bitbucket
Host bitbucket.org
    HostName bitbucket.org
    User git
    Port 22
    AddKeysToAgent yes
    IdentityFile /home/your_userid/.ssh/bitbucket
    IdentitiesOnly yes

• test access to bitbucket and other PCs and servers

# guest
pt-check-bb
# should see: You can use git to connect to Bitbucket.

# double-check needed ssh keys exist
pt-check-ssh-keys
# should see
 OK  : on VM: 'vm-02'
 OK  : file exists : '/home/guest_userid/.ssh/config'
 OK  : file exists : '/home/guest_userid/.ssh/bitbucket'
 # plus any others you added

install other ubuntu packages

pt-install-ubu full
# takes a few minutes

• check installation:

pt-install-ubu fast

setup fastnas and cpip shared directories

You may skip this section since these are specific to my setup.

• Fastnas a local NAS I use to hold shared data across all my projects and across Ubuntu, Windows and macOS.
• CPIP - see CPIP Packages. Holds downloads for C/C++ and other non-python languages

# cpip
sudo nano /etc/fstab
# add line:
# //10.0.0.24/fastnas /home/guest_userid/fastnas  cifs credentials=/etc/nas_cred,users,rw,uid=1000,gid=1000,file_mode=0664,dir_mode=0775,vers=3.0,_netdev 0 0

pt-check-cpip
# should see
-------: check fastnas
drwxrwxr-x  2 guest_userid guest_userid    0 Nov 23 19:46 .
drwxr-x--- 20 guest_userid guest_userid 4096 Nov 29 19:46 ..
drwxrwxr-x  2 guest_userid guest_userid    0 Nov 14 13:29 cpip
<snip>
# and 
-------: check cpip
drwxrwxr-x 2 guest_userid guest_userid    0 Nov 14 13:29 .
drwxrwxr-x 2 guest_userid guest_userid    0 Nov 23 19:46 ..
-rw-rw-r-- 1 guest_userid guest_userid   10 Oct 29 11:48 abc.cpp
drwxrwxr-x 2 guest_userid guest_userid    0 Oct 29 11:47 cpip
-rw-rw-r-- 1 guest_userid guest_userid 1263 Nov 14 13:29 cpip.json
<snip>

• reboot VM guest

sudo reboot

# re-login (ssh vm-02) and re-test
pt-install-ubu fast

pt-check-bashrc
# will indicate bashrc-ubu not found; will be installed later
pt-check-bb
pt-check-cpip
pt-check-groups
pt-check-hosts
pt-check-ssh-keys

SNAPSHOT 3 - has git, SSH access bitbucket, cpip, etc

At this point, the following are working:

• /etc/hosts setup
• git
• bitbucket key pair
• other SSH pairs
• other ubu common packages
• web-ver, cpip is set up
• no projects
• Take a snapshot:
  • click Machine
  • click "Take+" icon
  • enter "base-os v3" for Snapshot Name
  • use the list above for the Description
  • click OK

Install a project

In this doc, I'm going to install a project called "devcpp-app-template". This create a C++ sample project that I use as a template for a C++ application (not a library).

Note: there are other projects that are easy to install:

• devpy-app-template; use "devpy"
• devrb-app-template; use "devrb"
• pyalamake; use "pyalamake"; ensure the VM has the USB enabled to the Arduino board
• devino-app-template; use "devino"; ensure Arduino USB enabled
• gui-api-tkinter; use "guiapi"; must be run in the VM GUI; the others can be run in an SSH terminal
• swig-cpp; use "swig-cpp"
• proj-man; use "proj-man"; this is currently private. I will be releasing portions of it in the future

if you want to add others, see pt-project-install and pt-project-run-steps as a starting point

clone, install and test a project

• restart Guest VM
• login
• start a terminal

Or

• start an SSH terminal

clone and test a repo

pt-project-install devcpp
# note: this will install and then run the tests in pt-project-run-steps
# you will have to enter a password to do the installations

# if you encounter an error:
#  * exit the terminal
#  * restart it
#  * double check with: pt-check-bashrc
#
# note: the following will also be installed:
#  *  vfox
#  *  python
#  *  doxygen
#  *  ninja
#  *  googletest
#  *  llvm
#  *  clang
#  *  gcovr

# ensure vfox was installed and the paths were added to PATH
# restart terminal (recommended) or "source ~/.bashrc"
pt-check-bashrc

• To run install by itself:

pt-project-install devcpp install

• To run the test steps by themselves:

pt-project-install devcpp test

• At this point you can also run the other projects or you can restore the VM and run them as standalone installs as well

SNAPSHOT 4 - has your-project

At this point:

• your-project is installed and is functional
• basic functions are working
• Take a snapshot:
  • power off using Ubuntu power off
  • click Machine
  • click "Take+"
  • enter "base-os v4" for Snapshot Name
  • click OK

Some additional instructions

To restore to "base-os-???"

• use VM to power off the VM: click Machine | Shut Down
• use vbox manager to restore the snapshot
  • in the Snapshots tab
  • right click on the snapshot "base-os-???"
  • click "Restore..."
  • get a dlgbox, click Restore
• reopen the VM

To increase VM size

I did have a scenario where I guessed the expected disk size for the VM smaller than was actually needed. I tried various things. The only thing that worked was deleting all snapshots. Once that was done, the extra space appeared in gparted and so I was able to expand the VM.

• power off VM using VM
• delete all snapshots(!)

cd /home/guest_userid/VirtualBox VMs/vm-02-proj-tester
VBoxManage showmediuminfo disk "/path/to/your/vm/MyVM.vdi"
# note the value for "Capacity:"

VBoxManage modifymedium disk vm-02-proj-tester.vdi --resize 60000  # 60GB
# the new value has to be greater than the original value

VBoxManage showmediuminfo disk "/path/to/your/vm/MyVM.vdi"
# note the value for "Capacity:" is the new requested value

• ensure all snapshots are deleted (!)
• start VM, open a terminal

df -h
# should be /dev/sda2; check it is the new size: 60G

sudo apt install gparted
sudo gparted
# note the state of /dev/sda2 

# right click on /dev/sda2
# click resize
# click on green checkmark 
# click Apply
# click close
df -h
# should show 60G (or near it)
sudo reboot

• open a terminal and check the free space df -h