====== 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 [[https://youtu.be/Hzji7w882OY|video tutorial]]):

  - Install a recent version of [[https://www.virtualbox.org/|VirtualBox]] for your host OS (i.e. your computer's OS).\\ \ 
  - Create a new virtual machine for the guest OS with at least 15GB HDD, 4GB RAM and 32MB video:
    - 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//
    - Adjust memory size to //4096MB//
    - 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
    - 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\\ <WRAP important round>
Disabling audio for guest OS is especially important in VirtualBox v6.1.14 because that particular version broke audio support for OSX host (see [[https://forums.virtualbox.org/viewforum.php?f=8|numerous discussion threads]] for details). Older versions of VirtualBox seem not to have this problem, and the future versions, hopefully, will fix this issue.
</WRAP>
  - Install a recent version of [[https://ubuntu.com/download/desktop|Ubuntu distribution]] as your guest OS -- we recommend Ubuntu 22.04.3 LTS:
    - Download Ubuntu distribution ISO file: [[https://releases.ubuntu.com/22.04.3/ubuntu-22.04.3-desktop-amd64.iso|Ubuntu 22.04.3 LTS]]
    - Run the virtual machine and when prompted select the downloaded ISO file as your start-up disk
    - Go through the Ubuntu installation procedure -- see [[https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview|Ubuntu installation]] for guidance\\ \ 
  - In the guest OS, install the necessary Workcraft dependencies:
    - Install Java Runtime Environment by issuing the following commands in a terminal window:\\ <code shell>
sudo apt update
sudo apt install default-jdk
</code>
    - Install Graphviz DOT graph layout tools as follows:\\ <code shell>
sudo apt install graphviz
</code>
  - In the guest OS, install Workcraft and test it:
    - Download the latest version of Workcraft tarball file to your home directory
    - Extract Workcraft from the downloaded tarball:\\ <code shell>
tar xzf workcraft-*.tar.gz
</code>
    - Go to the Workcraft directory and start it by the following commands:\\ <code shell>
cd workcraft
./workcraft
</code>
  - 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 [[https://www.virtualbox.org/manual/ch04.html|Guest Additions]] for details)