Installing Workcraft in VirtualBox

This guide shows how to run Workcraft in a VirtualBox Ubuntu guest OS. Here are a couple of reasons for such a decision:

• Your OS is not fully compatible with Workcraft, e.g. due to a lack of 32-bit support as found in more recent versions of OSX (such as Catalina and newer) or;
• You want to run Workcraft in a controlled isolated environment, e.g. due to admin restrictions.

Below are some step-by-step setup instructions (If this is your first experience with VirtualBox, then you may want to follow this video tutorial):

1. Install a recent version of VirtualBox for your host OS (i.e. your computer's OS).
    
2. Create a new virtual machine for the guest OS with at least 15GB HDD, 4GB RAM and 32MB video:
   1. Click New button and configure the virtual machine as follows:
      • Name: Ubuntu 22.04
      • Machine folder: [use the default location]
      • Type: Linux
      • Version: Ubuntu 64-bit
   2. Adjust memory size to 4096MB
   3. Configure hard drive parameters:
      • Hard disk: Create a virtual hard disk now
      • Hard disk file type: VirtualBox Disk Image
      • Storage on physical hard disk: Dynamically allocated
      • File location and size: at least 15GB at the default location
   4. Adjust your virtual machine Settings as follows:
      • Under Display tab change Video Memory slider to at least 32MB
      • Under Audio tab untick Enable Audio – this is important for VirtualBox v6.1.14
        

        Disabling audio for guest OS is especially important in VirtualBox v6.1.14 because that particular version broke audio support for OSX host (see numerous discussion threads for details). Older versions of VirtualBox seem not to have this problem, and the future versions, hopefully, will fix this issue.

3. Install a recent version of Ubuntu distribution as your guest OS – we recommend Ubuntu 22.04.3 LTS:
   1. Download Ubuntu distribution ISO file: Ubuntu 22.04.3 LTS
   2. Run the virtual machine and when prompted select the downloaded ISO file as your start-up disk
   3. Go through the Ubuntu installation procedure – see Ubuntu installation for guidance
       
4. In the guest OS, install the necessary Workcraft dependencies:
   1. Install Java Runtime Environment by issuing the following commands in a terminal window:
      

      sudo apt update
      sudo apt install default-jdk

   2. Install Graphviz DOT graph layout tools as follows:
      

      sudo apt install graphviz

5. In the guest OS, install Workcraft and test it:
   1. Download the latest version of Workcraft tarball file to your home directory
   2. Extract Workcraft from the downloaded tarball:
      

      tar xzf workcraft-*.tar.gz

   3. Go to the Workcraft directory and start it by the following commands:
      

      cd workcraft
      ./workcraft

6. Optionally, you can also install guest OS additions for better display drivers and shared folders (via Devices→Insert Guest Additions CD image… menu of VirtualBox – see Guest Additions for details)