Updated detailed instructions for installing prerequisites (#1104)

* Updated order or steps and improved some details

* Removed vim as a dependency in the steps

* Added troubleshooting and separate check sections

Author: Lukenickerson

docs/devel/requirements-installation.md

@@ -1,26 +1,23 @@
 # Installing Requirements for the Kubernetes Dashboard
 
-This document assumes you have a Linux machine (or VM), and that you have a brand new Ubuntu Linux environment setup, but does not assume familiarity with Linux. If you don't have a Linux environment and you're using Windows, you may want to read instructions on how to setup a Linux VM on Windows first.
+These instructions are an elaboration on how to install the requirements listed on the [Getting Started page](getting-started.md). This document assumes you have a Linux machine (or VM), and that you have a brand new Ubuntu Linux environment setup, but does not assume familiarity with Linux. If you don't have a Linux environment and you're using Windows, you may want to read instructions on how to setup a Linux VM on Windows first.
 
 Before you begin please make sure you can connect to your Linux machine and login. Command line instructions for Linux will be shown starting with `$`; you should only type the text following the `$`.
 
-## Basic Setup
+## Initial System Setup
 Based on instructions from: https://docs.docker.com/engine/installation/linux/ubuntulinux/
 
-This will update Linux and get curl and vim, which you'll need later.
+This will update and upgrade Linux.
 ```
 $ sudo apt-get update
 $ sudo apt-get upgrade
-$ sudo apt-get install curl
-$ sudo apt-get install vim
 ```
-Unless you have another text editor you prefer, vim may be useful for beginners; instructions below use vim.
-
-### Initial checks
+### Check
 ```
 $ uname -r
 ```
-You should get `3.2.0-23-generic`, `3.13.0-88-generic`, or something similar depending on what the current version is.
+You should get `3.2.0-23-generic` or something similar depending on what the current version is.
+
 
 ```
 $ lsb_release -a
@@ -34,74 +31,60 @@ Release:        12.04
 Codename:       precise
 ```
 
-## Get Kubernetes
 
+## Install Helpful Programs
+Install some programs that we'll need later on, and verify that they're there. 
 ```
-$ curl -O https://storage.googleapis.com/kubernetes-release/release/v1.2.4/bin/linux/amd64/kubectl
-```
-*This will take a while.*
-
-## Get Vagrant on Linux
-
-```
-$ sudo apt-get install vagrant
-$ cd kubernetes
-$ export KUBERNETES_PROVIDER=vagrant
-$ ./cluster/kube-up.sh
+$ sudo apt-get install curl
+$ sudo apt-get install git
 ```
-*Note that the last command will throw a lot of errors.*
 
-
-## Install Git
+### Check
 ```
-$ sudo apt-get install git
+$ curl --version
 $ git --version
 ```
-These instructions were last tested with git version 1.7.9.5.
+These instructions were last tested with curl `7.22.0`, and git `1.7.9.5`.
 
+## Get Vagrant on Linux
 
-## Clone the Dashboard Repo
 ```
-git clone https://github.com/kubernetes/dashboard.git
+$ sudo apt-get install vagrant
+$ vagrant --version
+$ export KUBERNETES_PROVIDER=vagrant
+$ echo "export KUBERNETES_PROVIDER=vagrant" >> ~/.profile
 ```
+These instructions are using vagrant version 1.0.1.
 
-## Install Kubernetes Dashboard Requirements
-
-See the requirement list on the [Getting Started page](getting-started.md).
-
-### Install Docker
+## Install Docker
 
 Based on instructions from: https://docs.docker.com/engine/installation/linux/ubuntulinux/
 
-#### Setup
+### Setup
 ```
-$ sudo apt-get update
 $ sudo apt-get install apt-transport-https ca-certificates
 $ sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D
 ```
 
+Create a docker.list file with one command:
+
 ```
-$ cd /etc/apt/sources.list.d/
-$ sudo vim docker.list
+sudo bash -c 'echo "deb https://apt.dockerproject.org/repo ubuntu-precise main" > /etc/apt/sources.list.d/docker.list'
 ```
-* <kbd>i</kbd> = insert
-* Type `deb https://apt.dockerproject.org/repo ubuntu-precise main`
-* <kbd>Esc</kbd> = stops inserting
-* `:x` = exits and saves
 
 ```
 $ sudo apt-get update
 $ sudo apt-get purge lxc-docker
 $ apt-cache policy docker-engine
 ```
 
-#### Only needed for Ubuntu Precise 12.04
+### Only needed for Ubuntu Precise 12.04
 ```
 $ sudo apt-get update
 $ sudo apt-get install linux-image-generic-lts-trusty
 $ sudo reboot
 ```
-#### Do the Docker install
+### Do the Docker install
 ```
 $ sudo apt-get update
 $ sudo apt-get install docker-engine
@@ -111,7 +94,7 @@ $ sudo docker run hello-world
 
 You should receive a message that includes: `This message shows that your installation appears to be working correctly`.
 
-#### Configure Docker for your user
+### Configure Docker for your user
 Based on instructions from https://docs.docker.com/engine/installation/linux/ubuntulinux/#create-a-docker-group
 
 The example below uses "username" as a placeholder. Please substitute with the user you are logged in as, which can be seen by using `$ id`.
@@ -120,68 +103,117 @@ If you are running Linux in a VM using Vagrant, your username will be "vagrant".
 ```
 $ sudo groupadd docker
 $ sudo usermod -aG docker username
-$ env
 $ sudo reboot
+```
+
+#### Check
+
+```
 $ docker run hello-world
 ```
 
 You should get the same message as above, that includes: `This message shows that your installation appears to be working correctly`.
 
+For an additional check you can run these commands:
+
 `$ status docker` --> should say  "docker start/running, process [some number]"
+
 `$ docker ps` --> should show a table of information (or at least headers)
 
 
-### Install Go
+## Install Go
 
-Get the latest download URL from https://golang.org/dl/
+The instructions below are for install a specific version of Go (1.6.2 for linux amd64). If you want the latest Go version or have a different system, then you can get the latest download URL from https://golang.org/dl/
 ```
 $ wget https://storage.googleapis.com/golang/go1.6.2.linux-amd64.tar.gz
+$ sudo tar -C /usr/local -xzf go1.6.2.linux-amd64.tar.gz
+$ export PATH=$PATH:/usr/local/go/bin
+$ echo "export PATH=$PATH:/usr/local/go/bin" >> ~/.profile
 ```
-*Add Go to the path*
+
+### Check
+
 ```
 $ go version
+$ echo $PATH
 ```
-Should return something like `go version go1.6.2 linux/amd64`. Note that if you already had Go installed, ensure that `GO15VENDOREXPERIMENT` is unset.
+The Go version should return something like `go version go1.6.2 linux/amd64`. Note that if you already had Go installed, ensure that `GO15VENDOREXPERIMENT` is unset.
+
+## Install Node and NPM
+
+For some reason doing `sudo apt-get install nodejs` gives a much older version, so instead we will get the more recent version:
 
-### Install Node and NPM
-For some reason doing this...
-```
-$ sudo apt-get install nodejs
-```
-... gives a much older version, so instead we will get the more recent version:
 ```
 $ curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
 $ sudo apt-get install -y nodejs
+```
+
+### Check
+
+````
 $ node -v
 $ npm -v
 ```
-Should return `v6.2.1` and `3.9.3` respectively.
+The last time these instructions were updated, this returned `v6.3.1` and `3.10.3` respectively, but later versions will probably also work.
+
+## Install Java 7
 
-### Install Java 7
 ```
 $ sudo apt-get install openjdk-7-jre
+```
+
+### Check
+
+```
 $ java -version
 ```
 Should return `java version "1.7.0_101"`.
 
-### Install Gulp using npm 
+## Install Gulp using npm 
 ```
 $ sudo npm install --global gulp-cli
 $ sudo npm install --global gulp
+```
+
+### Check
+
+````
 $ gulp -v
 ```
 Should return `CLI version 3.9.1` and `Local version 3.9.1`.
 
+
+## Get Kubernetes
+
+Download the command line tool _kubectl_.
+
+```
+$ curl -O https://storage.googleapis.com/kubernetes-release/release/v1.2.4/bin/linux/amd64/kubectl
+```
+
+Clone the Dashboard and Kubernetes code from the GitHub repos. *This could take a while.*
+
+```
+$ git clone https://github.com/kubernetes/dashboard.git
+$ git clone https://github.com/kubernetes/kubernetes.git
+```
+
 ## Install Other Dashboard Dependencies Automatically with NPM
 
 ```
-$ cd /dashboard
+$ cd ~/dashboard
 $ npm install
 ```
-This will install all the dependencies that are in the `package.json` file.
+
+This will install all the dependencies that are in the `package.json` file in the dashboard repo. *This could take a while.*
 
 ## Run the Kubernetes Cluster
+
+Run the script included with the dashboard that checks out the latest Kubernetes and runs it in a Docker container.
+
 ```
+$ cd ~/dashboard
+$ sudo ./build/setup-docker.sh
 $ gulp local-up-cluster
 ```
 If you need to stop the cluster you can run `$ docker kill $(docker ps -aq)`
@@ -190,4 +222,40 @@ If you need to stop the cluster you can run `$ docker kill $(docker ps -aq)`
 $ gulp serve
 ```
 
+### Check
+
+Open up another terminal to your machine, and try to access the dashboard.
+
+```
+curl http://localhost:9090
+```
+This should return the HTML for the dashboard.
+
+### Continue
+
 Now you may [continue with the Getting Started guide](getting-started.md) to learn more about developing with the Kubernetes Dashboard.
+
+# Troubleshooting
+
+## Docker
+If you're having trouble with the `gulp local-up-cluster` step, you may want to investigate the docker containers.
+
+* `docker ps -a` lists all docker containers
+* `docker inspect name_of_container | grep "Error"` will look through the details of a docker container and display any errors.
+
+If you have a error like "linux mounts: Path /var/lib/kubelet is mounted on / but it is not a shared mount." you should try `sudo mount --bind /var/lib/kubelet /var/lib/kubelet` followed by `sudo mount --make-shared /var/lib/kubelet`. ([source](https://github.com/kubernetes/kubernetes/issues/4869#issuecomment-193640483))
+
+## Go
+
+If you run into an error like "Go is not on the path.", you may need to re-run `export PATH=$PATH:/usr/local/go/bin`
+
+## Helpful Linux Tips
+
+* `env` will show your environment variables. One common error is not having every directory needed in your PATH.
+
+Using *vim* to edit files may be helpful for beginners. 
+* `sudo apt-get install vim` will get *vim*
+* `sudo vim /path/to/folder/filename` will open the file you want to edit. 
+* <kbd>i</kbd> = insert
+* <kbd>Esc</kbd> = stops inserting
+* `:x` = exits and saves