{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# WSL2 & Docker Desktop Setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Docker Desktop Licensing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A typical Windows 10 installation does not include several of the tools needed to run the GridAPPS-D Platform  Several software packages need to be installed prior to installing GridAPPS-D in the next step\n",
    "\n",
    "    \n",
    "Installation Steps:\n",
    "\n",
    "* [1. Verify System Requirements](#Verify-System-Requirements)\n",
    "\n",
    "* [2. Verify OS Build](#Verify-OS-Build)\n",
    "\n",
    "* [3. Install Windows Subsystem for Linux](#Install-Windows-Subsystem-for-Linux)\n",
    "\n",
    "    * [3.1. Enable WSL](#Enable-WSL)\n",
    "    \n",
    "    * [3.2. Upgrade to WSL2](#Upgrade-to-WSL2)\n",
    "    \n",
    "    * [3.3. Install Linux Ubuntu OS](#Install-Linux-Ubuntu-OS)\n",
    "    \n",
    "    * [3.4. Set up Ubuntu in WSL](#Set-up-Ubuntu-in-WSL)\n",
    "    \n",
    "* [4. Install Docker for Windows](#Install-Docker-for-Windows)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is also possible to use Virtualbox to create a virtual Ubuntu Linux machine. This approach may be used if it is desired to use Eclipse, etc. for Java development. However, performance of Virtualbox is significantly worse than WSL2 for running GridAPPS-D simulations and python application development."
   ]
  },
  {
   "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": [
    "## Windows 10 OS Build Requirments\n",
    "\n",
    "To check your OS build, type `winver` in the Cortana seach bar:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![win-setup-run-winver](../images/1.1/win_setup_run_winver.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check to see if your OS is \n",
    "\n",
    "* For x64 systems: __Version 1903 or higher, with Build 18362 or higher.__\n",
    "\n",
    "* For ARM64 systems: __Version 2004 or higher, with Build 19041 or higher.__\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![win-setup-goodbad-winver](../images/1.1/win_setup_goodbad_winver.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If not, run __Windows Update__ to get the latest verion of Windows 10 available for your machine. It may take some time for the new OS to download. Multiple restarts are typical while upgrading the windows version."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Disconnect from Corporate VPN\n",
    "\n",
    "There is a known issue with WSL2 and some corporate / laboratory VPNs. During WSL2 and docker installation, the Domain Name Server is set to that of your corporate intranet if your machine is connected to a VPN. This will cause issues when accessing github, etc. from within WSL2.\n",
    "\n",
    "This issue has also been reported by users using Virtualbox VMs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install Windows Subsystem for Linux\n",
    "\n",
    "GridAPPS-D and the associated docker containers will run using the Windows Subsystem for Linux (WSL), which is a new feature to Windows 10 that enables linux code to run natively in Windows without a separate virtual machine. The steps in this section are also available on the [Microsoft website](https://docs.microsoft.com/en-us/windows/wsl/install-win10)\n",
    "\n",
    "### Enable WSL\n",
    "\n",
    "Open Windows PowerShell as an administrator:\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![open-powershell](../images/1.1/win_setup_open_powershell.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Enable WSL by entering\n",
    "\n",
    "`dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![enable-wsl2](../images/1.1/win_setup_enable_wsl2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, without restarting, enable the virtual machine platform by entering\n",
    "\n",
    "`dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart`\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![enable-VM](../images/1.1/win_setup_enable_VM.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When completed, restart your machine. It may take a few minutes for the new settings to be applied while restarting."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Upgrade to WSL2\n",
    "\n",
    "Download the latest WSL2 package .msi installer from the [Microsoft repository](https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi)\n",
    "\n",
    "Run the update package to install WSL2 using the wizard:\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![WSL-wizard](../images/1.1/win_setup_WSL_wizard.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Open Windows PowerShell again and update the settings to use WSL2 by entering\n",
    "\n",
    "`wsl --set-default-version 2`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Install Linux Ubuntu OS\n",
    "\n",
    "Open the Microsoft Store app, and search for `Ubuntu` and install the desired version (available versions are 16.04, 18.04, and 20.04)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![ubuntu-store](../images/1.1/win_setup_ubuntu_store.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "When it has finished downloading, click `Launch`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![ubuntu-launch](../images/1.1/win_setup_ubuntu_launch.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Set up Ubuntu in WSL\n",
    "\n",
    "Wait for the Ubuntu OS to install.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![ubuntu-setup](../images/1.1/win_setup_ubuntu_setup.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Select a username and password. These do not need to be the same as your Windows or Microsoft Account login.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![ubuntu-username2](../images/1.1/win_setup_ubuntu_username2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install Docker for Windows\n",
    "\n",
    "Download and run __Docker Desktop for Windows__ from [Docker Hub](https://desktop.docker.com/win/stable/Docker%20Desktop%20Installer.exe)\n",
    "\n",
    "Be sure to select \"__Install required components for WSL2__\"\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![docker-wizard](../images/1.1/win_setup_docker_wizard.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "\n",
    "After restarting your machine, Docker should start automatically, and you will see a notification stating \"__Linux WSL2 containers are starting__\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![containers-starting](../images/1.1/win_setup_containers_starting.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  }
 ],
 "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
}