added a MacOS quickstart (and refactored)
Change-Id: I1345f6a3030b8838d3fd41987a7a06d3ad7fd74e
diff --git a/SUMMARY.md b/SUMMARY.md
index 9c2393b..6ec9c47 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -3,6 +3,8 @@
* [Overview](overview.md)
* [Navigating CORD](navigate.md)
* [Quick Start](quickstart.md)
+ * [MacOS](macos.md)
+ * [Linux](linux.md)
* [Installation Guide](README.md)
* [Prerequisites](prereqs/README.md)
* [Hardware Requirements](prereqs/hardware.md)
diff --git a/linux.md b/linux.md
new file mode 100644
index 0000000..6e22f34
--- /dev/null
+++ b/linux.md
@@ -0,0 +1,224 @@
+# Quick Start: Linux
+
+This section walks you through an example installation sequence on
+Linux, assuming a fresh install of Ubunto 16.04.
+
+## Prerequisites
+
+You need to first install Docker and Python:
+
+```shell
+sudo apt update
+sudo apt-get install python
+sudo apt-get install python-pip
+pip install requests
+sudo apt install -y docker.io
+sudo systemctl start docker
+sudo systemctl enable docker
+```
+
+Now, verify the docker version.
+
+```shell
+docker --version
+```
+
+## Minikube & Kubectl
+
+Install `minikube` and `kubectl`:
+
+```shell
+curl -Lo minikube
+https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
+chmod +x minikube
+sudo mv minikube /usr/local/bin/
+curl -Lo kubectl https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl && chmod +x kubectl
+curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl
+chmod +x ./kubectl
+sudo mv ./kubectl /usr/local/bin/kubectl
+```
+
+Issue the following commands:
+
+```shell
+export MINIKUBE_WANTUPDATENOTIFICATION=false
+export MINIKUBE_WANTREPORTERRORPROMPT=false
+export MINIKUBE_HOME=$HOME
+export CHANGE_MINIKUBE_NONE_USER=true
+mkdir -p $HOME/.kube
+touch $HOME/.kube/config
+
+export KUBECONFIG=$HOME/.kube/config
+```
+
+Navigate to the `/usr/local/bin/` directory and issue the following
+commands. Make sure there are no errors afterwards:
+
+```shell
+sudo -E ./minikube start --vm-driver=none
+```
+
+You can run
+
+```shell
+kubectl cluster-info
+```
+
+to verify that your Minikube cluster is up and running.
+
+## Export the KUBECONFIG File
+
+Locate the `KUBECONFIG` file:
+
+```shell
+sudo updatedb
+locate kubeconfig
+```
+
+Export a `KUBECONFIG` variable containing the path to the
+configuration file found above. For example, If your `U`
+file was located in the `/var/lib/localkube/kubeconfig` directory,
+the command you issue would look like this:
+
+```shell
+export KUBECONFIG=/var/lib/localkube/kubeconfig
+```
+
+## Download CORD
+
+There are two general ways you might download CORD. The following
+walks through both, but you need to follow only one. (For simplicity, we
+recommend the first.)
+
+The first simply clones the CORD `helm-chart` repository using `git`.
+This is sufficient for downloading just the Helm charts you will need
+to deploy the set of containers that comprise CORD. These containers
+will be pulled down from DockerHub.
+
+The second uses the `repo` tool to download all the source code that
+makes up CORD, including the Helm charts needed to deploy the CORD
+containers. You might find this useful if you want look at the
+interals of CORD more closely.
+
+In either case, following these instructions will result in a
+directory `~/cord/helm-charts`, which will be where you go next to
+continue the installation process.
+
+### Download: `git clone`
+
+Create a CORD directory and run the following `git` command in it:
+
+```shell
+mkdir ~/cord
+cd ~/cord
+git clone https://gerrit.opencord.org/helm-charts
+cd helm-charts
+```
+
+### Download: `repo`
+
+Make sure you have a `bin/` directory in your home directory and
+that it is included in your path:
+
+```shell
+mkdir ~/bin
+PATH=~/bin:$PATH
+```
+
+Download the Repo tool and ensure that it is executable:
+
+```shell
+curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
+chmod a+x ~/bin/repo
+```
+
+Make a `/cord` directory and navigate into it:
+
+```shell
+mkdir ~/cord
+cd ~/cord
+```
+
+Configure `git` with your real name and email address:
+
+```shell
+git config --global user.name "Your Name"
+git config --global user.email "you@example.com"
+```
+
+Initialize `repo` and download the CORD source tree to your working
+directory:
+
+```shell
+repo init -u https://gerrit.opencord.org/manifest -b master
+repo sync
+```
+
+## Helm
+
+Run the Helm installer script that will automatically grab the latest
+version of the Helm client and install it locally:
+
+```shell
+curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get > get_helm.sh
+chmod 700 get_helm.sh
+./get_helm.sh
+```
+
+## Tiller
+
+Issue the following:
+
+```shell
+sudo helm init
+sudo kubectl create serviceaccount --namespace kube-system tiller
+sudo kubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller
+sudo kubectl patch deploy --namespace kube-system tiller-deploy -p '{"spec":{"template":{"spec":{"serviceAccount":"tiller"}}}}'
+sudo helm init --service-account tiller --upgrade
+```
+
+Install `socat` to fix a port-forwarding error:
+
+```shell
+sudo apt-get install socat
+```
+
+Issue the following and make sure no errors come up:
+
+```shell
+helm ls
+```
+
+## Deploy CORD Helm Charts
+
+Deploy the service profiles corresponding to the `xos-core`,
+`base-kubernetes`, and `demo-simpleexampleservice` helm-charts:
+
+```shell
+cd ~/cord/helm-charts
+helm init
+sudo helm dep update xos-core
+sudo helm install xos-core -n xos-core
+sudo helm dep update xos-profiles/base-kubernetes
+sudo helm install xos-profiles/base-kubernetes -n base-kubernetes
+sudo helm dep update xos-profiles/demo-simpleexampleservice
+sudo helm install xos-profiles/demo-simpleexampleservice -n demo-simpleexampleservice
+```
+
+Use `kubectl get pods` to verify that all containers in the profile
+are successful and none are in the error state.
+
+> **Note:** It will take some time for the various helm charts to
+> deploy and the containers to come online. The `tosca-loader
+> `container may error and retry several times as they wait for
+> services to be dynamically loaded. This is normal, and eventually
+> the `tosca-loader` containers will enter the completed state:
+
+## Next Steps
+
+This completes our example walk-through. At this point, you can do one
+of the following:
+
+* Explore other [installation options](README.md).
+* Take a tour of the [operational interfaces](operating_cord/general.md).
+* Drill down on the internals of [SimpleExampleService](simpleexampleservice/simple-example-service.md).
diff --git a/macos.md b/macos.md
new file mode 100644
index 0000000..59e4b6d
--- /dev/null
+++ b/macos.md
@@ -0,0 +1,148 @@
+# Quick Start: MacOS
+
+This section walks you through an example installation sequence on
+MacOS. It was tested on version 10.12.6.
+
+## Prerequisites
+
+You need to install Docker. Visit `https://docs.docker.com/docker-for-mac/install/` for instructions.
+
+You also need to install VirtualBox. Visit `https://www.virtualbox.org/wiki/Downloads` for instructions.
+
+The following assumes you've installed the Homebrew package manager. Visit
+`https://brew.sh/` for instructions.
+
+## Install Minikube and Kubectl
+
+To install Minikube, run the following command:
+
+```shell
+curl -Lo minikube https://storage.googleapis.com/minikube/releases/v0.28.0/minikube-darwin-amd64 && chmod +x minikube && sudo mv minikube /usr/local/bin/
+```
+To install Kubectl, run the following command:
+
+```shell
+brew install kubectl
+```
+
+## Install Helm and Tiller
+
+The following installs both Helm and Tiller.
+
+```shell
+brew install kubernetes-helm
+```
+
+## Bring Up a Kubernetes Cluster
+
+Start a minikube cluster as follows. This automatically runs inside VirtualBox.
+
+```shell
+minikube start
+```
+
+To see that it's running, type
+
+```shell
+kubectl cluster-info
+```
+
+You should see something like the following
+
+```shell
+Kubernetes master is running at https://192.168.99.100:8443
+KubeDNS is running at https://192.168.99.100:8443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
+
+To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
+```
+
+You can also see how the cluster is configured by looking at `~/.kube/config`.
+Other tools described on this page use this configuration file to find your cluster.
+
+If you want, you can see minikube running by looking at the VirtualBox dashboard.
+Or alternatively, you can visit the Minikube dashboard:
+
+```shell
+minikube dashboard
+```
+
+As a final setp, you need to start Tiller on the Kubernetes cluster.
+
+```shell
+helm init
+```
+
+## Download CORD Helm-Charts
+
+You don't need to download all of CORD. You just need to download a set of helm charts. They will, in turn, download a collection of CORD containers from Docker
+Hub. The rest of this section assumes all CORD-related downloads are placed in
+directory `~/cord`.
+
+```shell
+mkdir ~/cord
+cd ~/cord
+git clone https://gerrit.opencord.org/helm-charts
+cd helm-charts
+```
+
+## Bring Up CORD
+
+Deploy the service profiles corresponding to the `xos-core`,
+`base-kubernetes`, and `demo-simpleexampleservice` helm-charts.
+To do this, execute the following from the `~/cord/helm-charts` directory.
+
+```shell
+helm dep update xos-core
+helm install xos-core -n xos-core
+helm dep update xos-profiles/base-kubernetes
+helm install xos-profiles/base-kubernetes -n base-kubernetes
+helm dep update xos-profiles/demo-simpleexampleservice
+helm install xos-profiles/demo-simpleexampleservice -n demo-simpleexampleservice
+```
+
+Use `kubectl get pods` to verify that all containers in the profile
+are successful and none are in the error state.
+
+> **Note:** It will take some time for the various helm charts to
+> deploy and the containers to come online. The `tosca-loader`
+> container may error and retry several times as it waits for
+> services to be dynamically loaded. This is normal, and eventually
+> the `tosca-loader` will enter the completed state.
+
+When all the containers are successfully up and running, `kubectl get pod`
+will return output that looks something like this:
+
+```shell
+NAME READY STATUS RESTARTS AGE
+base-kubernetes-kubernetes-55c55bd897-rn9ln 1/1 Running 0 2m
+base-kubernetes-tosca-loader-vs6pv 1/1 Running 1 2m
+demo-simpleexampleservice-787454b84b-ckpn2 1/1 Running 0 1m
+demo-simpleexampleservice-tosca-loader-4q7zg 1/1 Running 0 1m
+xos-chameleon-6f49b67f68-pdf6n 1/1 Running 0 2m
+xos-core-57fd788db-8b97d 1/1 Running 0 2m
+xos-db-f9ddc6589-rtrml 1/1 Running 0 2m
+xos-gui-7fcfcd4474-prhfb 1/1 Running 0 2m
+xos-redis-74c5cdc969-ppd7z 1/1 Running 0 2m
+xos-tosca-7c665f97b6-krp5k 1/1 Running 0 2m
+xos-ws-55d676c696-pxsqk 1/1 Running 0 2m
+```
+
+## Visit CORD Dashboard
+
+Finally, to view the CORD dashboard, run the following:
+
+```shell
+minikube service xos-gui
+```
+
+This will launch a window in your default browser. Administrator login
+and password are defined in `~/cord/helm-charts/xos-core/values.yaml`.
+
+## Next Steps
+
+This completes our example walk-through. At this point, you can do one
+of the following:
+
+* Explore other [installation options](README.md).
+* Take a tour of the [operational interfaces](operating_cord/general.md).
+* Drill down on the internals of [SimpleExampleService](simpleexampleservice/simple-example-service.md).
diff --git a/quickstart.md b/quickstart.md
index ece620c..bf1354d 100644
--- a/quickstart.md
+++ b/quickstart.md
@@ -1,232 +1,16 @@
# Quick Start
-This section walks you through one example installation sequence.
-If you'd prefer to understand the
-installation process in more depth, including the full range of
-deployment options, you might start with the [Installation Guide](README.md)
+This section walks you through an example installation sequence on two
+different platforms. If you'd prefer to understand the installation
+process in more depth, including the full range of deployment options,
+you might start with the [Installation Guide](README.md) instead.
-The following describes how to install the R-CORD profile, plus a
-`SimpleExampleService`, on a single Linux box. Once you complete these
+This Quick Start describes how to install the R-CORD profile, plus a
+`SimpleExampleService`, on a single machine. Once you complete these
steps, you might be interested in jumping ahead to the
[SimpleExampleService Tutorial](simpleexampleservice/simple-example-service.md)
-to learn more about the make-up of a CORD service.
+to learn more about the make-up of a CORD service. Another option
+would be to explore CORD's [operational interfaces](operating_cord/general.md).
-## Python & Docker
-
-After a fresh install of Ubuntu 16.04 Server, install Docker and Python:
-
-```shell
-sudo apt update
-sudo apt-get install python
-sudo apt-get install python-pip
-pip install requests
-sudo apt install -y docker.io
-sudo systemctl start docker
-sudo systemctl enable docker
-```
-
-Now, verify the docker version.
-
-```shell
-docker --version
-```
-
-## Minikube & Kubectl
-
-Install `minikube` and `kubectl`:
-
-```shell
-curl -Lo minikube
-https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
-chmod +x minikube
-sudo mv minikube /usr/local/bin/
-curl -Lo kubectl https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl && chmod +x kubectl
-curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl
-chmod +x ./kubectl
-sudo mv ./kubectl /usr/local/bin/kubectl
-```
-
-Issue the following commands:
-
-```shell
-export MINIKUBE_WANTUPDATENOTIFICATION=false
-export MINIKUBE_WANTREPORTERRORPROMPT=false
-export MINIKUBE_HOME=$HOME
-export CHANGE_MINIKUBE_NONE_USER=true
-mkdir -p $HOME/.kube
-touch $HOME/.kube/config
-
-export KUBECONFIG=$HOME/.kube/config
-```
-
-Navigate to the `/usr/local/bin/` directory and issue the following
-commands. Make sure there are no errors afterwards:
-
-```shell
-sudo -E ./minikube start --vm-driver=none
-```
-
-You can run
-
-```shell
-kubectl cluster-info
-```
-
-to verify that your Minikube cluster is up and running.
-
-## Export the KUBECONFIG File
-
-Locate the `KUBECONFIG` file:
-
-```shell
-sudo updatedb
-locate kubeconfig
-```
-
-Export a `KUBECONFIG` variable containing the path to the
-configuration file found above. For example, If your `U`
-file was located in the `/var/lib/localkube/kubeconfig` directory,
-the command you issue would look like this:
-
-```shell
-export KUBECONFIG=/var/lib/localkube/kubeconfig
-```
-
-## Download CORD
-
-There are two general ways you might download CORD. The following
-walks through both, but you need to follow only one. (For simplicity, we
-recommend the first.)
-
-The first simply clones the CORD `helm-chart` repository using `git`.
-This is sufficient for downloading just the Helm charts you will need
-to deploy the set of containers that comprise CORD. These containers
-will be pulled down from DockerHub.
-
-The second uses the `repo` tool to download all the source code that
-makes up CORD, including the Helm charts needed to deploy the CORD
-containers. You might find this useful if you want look at the
-interals of CORD more closely.
-
-In either case, following these instructions will result in a
-directory `~/cord/helm-charts`, which will be where you go next to
-continue the installation process.
-
-### Download: `git clone`
-
-Create a CORD directory and run the following `git` command in it:
-
-```shell
-mkdir ~/cord
-cd ~/cord
-git clone https://gerrit.opencord.org/helm-charts
-cd helm-charts
-```
-
-### Download: `repo`
-
-Make sure you have a `bin/` directory in your home directory and
-that it is included in your path:
-
-```shell
-mkdir ~/bin
-PATH=~/bin:$PATH
-```
-
-Download the Repo tool and ensure that it is executable:
-
-```shell
-curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
-chmod a+x ~/bin/repo
-```
-
-Make a `/cord` directory and navigate into it:
-
-```shell
-mkdir ~/cord
-cd ~/cord
-```
-
-Configure `git` with your real name and email address:
-
-```shell
-git config --global user.name "Your Name"
-git config --global user.email "you@example.com"
-```
-
-Initialize `repo` and download the CORD source tree to your working
-directory:
-
-```shell
-repo init -u https://gerrit.opencord.org/manifest -b master
-repo sync
-```
-
-## Helm
-
-Run the Helm installer script that will automatically grab the latest
-version of the Helm client and install it locally:
-
-```shell
-curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get > get_helm.sh
-chmod 700 get_helm.sh
-./get_helm.sh
-```
-
-## Tiller
-
-Issue the following:
-
-```shell
-sudo helm init
-sudo kubectl create serviceaccount --namespace kube-system tiller
-sudo kubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller
-sudo kubectl patch deploy --namespace kube-system tiller-deploy -p '{"spec":{"template":{"spec":{"serviceAccount":"tiller"}}}}'
-sudo helm init --service-account tiller --upgrade
-```
-
-Install `socat` to fix a port-forwarding error:
-
-```shell
-sudo apt-get install socat
-```
-
-Issue the following and make sure no errors come up:
-
-```shell
-helm ls
-```
-
-## Deploy CORD Helm Charts
-
-Deploy the service profiles corresponding to the `xos-core`,
-`base-kubernetes`, and `demo-simpleexampleservice` helm-charts:
-
-```shell
-cd ~/cord/helm-charts
-helm init
-sudo helm dep update xos-core
-sudo helm install xos-core -n xos-core
-sudo helm dep update xos-profiles/base-kubernetes
-sudo helm install xos-profiles/base-kubernetes -n base-kubernetes
-sudo helm dep update xos-profiles/demo-simpleexampleservice
-sudo helm install xos-profiles/demo-simpleexampleservice -n demo-simpleexampleservice
-```
-
-Use `kubectl get pods` to verify that all containers in the profile
-are successful and none are in the error state.
-
-> **Note:** It will take some time for the various helm charts to
-> deploy and the containers to come online. The `tosca-loader
-> `container may error and retry several times as they wait for
-> services to be dynamically loaded. This is normal, and eventually
-> the `tosca-loader` containers will enter the completed state:
-
-## Next Steps
-
-This completes our example walk-through. At this point, you can do one
-of the following:
-
-* Explore other [installation options](README.md).
-* Take a tour of the [operational interfaces](operating_cord/general.md).
-* Drill down on the internals of [SimpleExampleService](simpleexampleservice/simple-example-service.md).
+* [MacOS](macos.md)
+* [Linux](linux.md)