{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# VirtualBox VM Setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Docker Desktop Licensing**\n",
    "\n",
    "As of Jan 31, 2022, a paid license is required for most Windows users to run Docker Desktop. \n",
    "\n",
    "Docker Desktop is a third-party Windows program used to run the containerized software packages, such as GridAPPS-D.\n",
    "\n",
    "Personal, small business, and education may still be permitted under ther free personal license of docker (referenced in these instructions).\n",
    "\n",
    "For more information, see [Docker Pricing & Licensing FAQ](https://www.docker.com/pricing/faq)\n",
    "\n",
    "**VirtualBox VM**\n",
    "\n",
    "A VirtualBox installation provides an option for running GridAPPS-D on Windows machines without a Docker Desktop license."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "   \n",
    "Installation Steps:\n",
    "\n",
    "* [1. Verify System Requirements](#Verify-System-Requirements)\n",
    "\n",
    "* [2. Download VirtualBox](#Download-VirtualBox)\n",
    "\n",
    "* [3. Download Ubuntu Linux OS](#Download-Ubuntu-Linux-OS)\n",
    "\n",
    "* [4. Create an Ubuntu VM](#Create-an-Ubuntu-VM)\n",
    "\n",
    "* [5. Configure the Ubuntu VM](#Configure-the-Ubuntu-VM)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## System Requirements\n",
    "\n",
    "* __OS:__ \n",
    "    * Windows 10, Version 2004 or higher, with Build 19041 or higher\n",
    "* __RAM:__ \n",
    "    * 8GB (_absolute minimum_ for 13 and 123 node models, _may encounter memory overload during installation_ );\n",
    "    * 16GB (preferred for small models, minimum for 8500/9500 node models);\n",
    "    * 32GB (recommended for application development)\n",
    "* __Disk Space:__ \n",
    "    * 15GB required for installation\n",
    "    \n",
    "__Note:__ The download size is quite large, so it is recommended to use a fiber or ethernet interent connection, rathered than a metered hotspot to avoid excessive data usage charges."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Download VirtualBox\n",
    "\n",
    "Download the latest version from the [VirtualBox website](https://www.virtualbox.org/wiki/Downloads)\n",
    "\n",
    "Run the .exe file after the download is complete."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![vb-wizard](../images/1.1/01_virtualbox_wizard.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Continue with all default options to install VirtualBox\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![vb-defaults](../images/1.1/02_virtualbox_wizard.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After the installation wizard has finished, select \"Start Orace VM Virtualbox after installation\" and click \"Finish\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![vb-wizard-done](../images/1.1/04_virtualbox_wizard.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Download Ubuntu Linux OS\n",
    "\n",
    "Download Ubuntu 20.04.03 from the [OSBoxes.org website](https://www.osboxes.org/ubuntu/)\n",
    "\n",
    "Alternatively, you can download the installer directly from the associated [SourceForge link](https://sourceforge.net/projects/osboxes/files/v/vb/55-U-u/20.04/20.04.3/Desktop/64bit.7z/download)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![linux](../images/1.1/06_ubuntu_20.04.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You will need 7-Zip to unzip the download file. You can download and install the tool from the [7-Zip Website](https://www.7-zip.org/)\n",
    "\n",
    "After the download is complete, right-click on the zipped download and unzip the Ubuntu OS file in a directory where you can easily find it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![7-zip](../images/1.1/07_unzip.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create an Ubuntu VM\n",
    "\n",
    "Return to VirtualBox and click `New` to create a new virtual machine."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![new-vm](../images/1.1/05_virtualbox_home.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Enter `Ubuntu` in the space for `Name:`. VirtualBox should automatically populate the remaining forms in the window. Click Next to continue."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![enable-wsl2](../images/1.1/08_new_VM.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**It is recommended to select at least 8 GB of RAM for the VM instance.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![select-ram](../images/1.1/09_pick_RAM.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Select `Use an existing virtual disk file` and click on the folder icon"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![select-disk-1](../images/1.1/10_hard_disk.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Click \"Add\" to add the downloaded disk image for Ubuntu 20.04.3 that you unzipped previously."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![select-os-file](../images/1.1/12_select_os_file.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then click `Choose` and `Create` to create the new virtual machine."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![choose](../images/1.1/13_selected.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![create](../images/1.1/14_create.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configure the Ubuntu VM"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Click the `Settings` icon to configure the VM.\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![settings-1](../images/1.1/15_settings.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, select `System` from the left menu and then the `Processor` tab.\n",
    "\n",
    "It is recommended to allocate 4 CPU cores to GridAPPS-D (2 at minimum)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![cpu](../images/1.1/15_cpu.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, select `Display` from the left menu. Increase the `Video Memory` to at least 32 MB.\n",
    "\n",
    "Check the `Acceleration` box to enable 3D acceleration of graphics windows."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![display](../images/1.1/16_display.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Click `OK` to save the settings. Then, start the VM by right-clicking on the VM instance and selecting `Normal Start`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![start](../images/1.1/17_start.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After the VM has launched, login with the default username and password:\n",
    "* username: osboxes.org\n",
    "* password: osboxes.org"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![login](../images/1.1/18_login.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Enable clipboard sharing for copy-paste capability between your windows and virtualbox environments."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![clipboard](../images/1.1/19_clipboard.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Click the `Devices` menu and select `Insert Guest Additions CD image ...` and follow the prompts to load missing components."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![devices](../images/1.1/19_devices.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![installed](../images/1.1/20_installed.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After all modules are built, open a new terminal and reboot the VM using `sudo reboot`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![reboot](../images/1.1/21_reboot.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, update all modules and install git and pip by running \n",
    "\n",
    "* `sudo apt-get install update`\n",
    "\n",
    "* `sudo apt-get install git`\n",
    "\n",
    "* `sudo apt-get install pip`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![update](../images/1.1/22_get_update.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![install-git](../images/1.1/23_install_git.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![pip](../images/1.1/24_install_pip.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![gridappsd-logo](../../images/GridAPPS-D_narrow.png)"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Tags",
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}