tools/deploy/instructions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Lucida Installation Instructions\n",
    "## November 29, 2016"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Overview\n",
    "\n",
    "In this tutorial, you will deploy **Lucida** on your Mac. Once it is deployed, follow [tutorial.pdf](../../tutorial.pdf) for demo. The entire process may take several hours.\n",
    "\n",
    "As bonus, you will learn:\n",
    "\n",
    "1. How to set up a **Ubuntu virtual machine**\n",
    "\n",
    "2. How to execute some **basic Linux commands**\n",
    "\n",
    "3. How to use **Docker and Kubernetes**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Prerequisite: Mac OS X"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Steps\n",
    "\n",
    "**Important**: Please copy and paste the `command line instructions` rather than manually type."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 1\n",
    "Download the Ubuntu 14.04 **64-bit** iso image from [`http://releases.ubuntu.com/14.04/`](http://releases.ubuntu.com/14.04/). Docker does not work on a 32-bit OS, so please choose a 64-bit version. Simply download to your file system without extracting/unzipping. It may take a while\n",
    "![](img/1.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 2\n",
    "Install Parallel Desktop 11 for Mac from [`http://www.parallels.com/products/desktop/download/`](http://www.parallels.com/products/desktop/download/)  and open it\n",
    "![](img/2.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 3\n",
    "Click `+` to create a new Ubuntu 14.04 virtual machine\n",
    "![](img/3.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 4\n",
    "Click the middle button \"Install Windows or another OS from a DVD or image file\". We are installing Ubuntu from the image file you downloaded in step 1\n",
    "![](img/4.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 5\n",
    "Locate the Ubuntu 14.04 64-bit iso image, then click `Continue`\n",
    "![](img/5.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 6\n",
    "Set password, click `Continue`, name it to `Lucida`, check the box `Custom Settings before installation`, then click `Continue`\n",
    "![](img/6.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 7\n",
    "Locate `Hardware`, click the lock button to make changes, and then set memory to near the maximum amount in the green range (for example, 8 GB in the below case). Usually, anywhere between 4 GB and 8 GB is fine\n",
    "![](img/7.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 8\n",
    "Close the window, click `Continue`, and wait until Ubuntu 14.04 is set up. It may take a while\n",
    "![](img/8.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 9\n",
    "Click the search button, locate `Terminal`, and open it\n",
    "![](img/9.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 10\n",
    "Run `wget https://github.com/claritylab/lucida/archive/master.zip` to download Lucida Github repo\n",
    "![](img/10.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 11\n",
    "Run `unzip master.zip` followed by `ls` to see a directory `lucida-master/`\n",
    "![](img/11.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 12\n",
    "Run `wget -qO- https://get.docker.com/ | sh` followed by `sudo usermod -aG docker $(whoami)` to install Docker. After that, log out and back in for this to take effect\n",
    "![](img/12.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 13\n",
    "Open the terminal again, and run `sudo start docker`\n",
    "![](img/13.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 14\n",
    "Run `cd lucida-master/tools/deploy/` followed by `sudo ./cluster_up_linux.sh` to start a Kubernetes cluster\n",
    "![](img/14.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 15\n",
    "Run `sudo chown -R $(whoami) /home/$(whoami)/.kube/config` to give yourself permission to a Kubernetes-related directory\n",
    "![](img/15.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 16\n",
    "Run `sudo ./start_services.sh` followed by `kubectl get pod` to start all the services and monitor the status. Kubernetes starts downloading the images, so please wait until the status of every pod becomes `running`. It may take a while\n",
    "![](img/16.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 17\n",
    "*Inside Ubuntu*, visit `localhost:30000` in your browser. If you want to access Lucida from OS X, please set up port forwarding\n",
    "![](img/17.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Congratulations!\n",
    "It's done. Lucida is runnin in your virtual machine.\n",
    "Follow [tutorial.pdf](../../tutorial.pdf) for demo."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### How to uninstall?\n",
    "\n",
    "- If you want to remove Lucida along with Ubuntu, simply go back to the control panel of Parallel Desktop, right click the virtual machine, and select \"Remove\"\n",
    "\n",
    "- If you want to remove Lucida but keep using Ubuntu, run the following commands **twice** to stop and remove all the Docker containers currently running in the virtual machine:\n",
    "\n",
    "```\n",
    "dockerlist=$(docker ps -a -q)\n",
    "if [ \"${dockerlist}\" != \"\" ]; then\n",
    "  for d in ${dockerlist}; do\n",
    "    echo \"***** ${d}\"\n",
    "    docker stop ${d} 2>&1 > /dev/null\n",
    "    docker rm ${d} 2>&1 > /dev/null\n",
    "    done\n",
    "  fi\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python [Root]",
   "language": "python",
   "name": "Python [Root]"
  },
  "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.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}