Updates for referral code, additional instructions

guide/deployment_digitalocean.md

 # Deployment guide for DigitalOcean
 
+In this guide we will be using the `docker-machine` tool to provision a number of Docker Swarm nodes then we'll connect them together and deploy OpenFaaS. Before you get started - sign up to [Digital Ocean here to get free credits](https://m.do.co/c/8d4e75e9886f). Once you've signed up come back to the tutorial. 
+
 ## Create DigitalOcean API Access Token
-Follow DigitalOceans instructions to create a Personal Access Token with **Read** and **Write** permissions, give the token a descriptive name for example `openfaas-getting-started`.
-- https://www.digitalocean.com/community/tutorials/how-to-use-the-digitalocean-api-v2#how-to-generate-a-personal-access-token
 
-Set an environment variable with your token value.
+Follow the [DigitalOcean instructions here](https://www.digitalocean.com/community/tutorials/how-to-use-the-digitalocean-api-v2#how-to-generate-a-personal-access-token) to create a Personal Access Token with **Read** and **Write** permissions, give the token a descriptive name for example `openfaas-getting-started`.
+
+Now set an environment variable with the new token value.
+
 ```
-export DOTOKEN=738cb0cd2jfhu84c33hu...
+$ export DOTOKEN=738cb0cd2jfhu84c33hu...
 ```
 
+> If you want to make this permanent, you can insert the value into your `~/.bash_profile` file.
+
 ## Install Docker Machine
-Follow Dockers instructions to install Docker Machine on your laptop/desktop.
-- https://docs.docker.com/machine/install-machine/
+
+Type in `docker-machine` to see if you already have the tool installed this is normally bundled with Docker for Mac/Windows. If not then you can download [Docker Machine here](https://docs.docker.com/machine/install-machine/). 
 
 ## Create Docker Nodes
-Use Docker Machine to create Docker nodes, the example below creates 3 droplets in the NYC3 zone, if you want to deploy only one Droplet change `"1 2 3"` to `"1"`.
+
+Use Docker Machine to create Docker hosts or nodes. On Digital Ocean your hosts or VMs (Virtual Machines) are called *Droplets* and will run a full version of Linux. Note: you'll be able to connect to any of your droplets with `ssh` later on.
+
+The example below creates 3 droplets in the NYC3 zone, if you want to deploy only one Droplet change `"1 2 3"` to `"1"`.
 
 This process will take a few minutes as Droplets are created and Docker installed.
 ```
@@ -28,11 +36,12 @@ for i in 1 2 3; do
         node-$i;
 done
 ```
+
 List the newly created Docker nodes.
+
 ```
-docker-machine ls
-```
-```
+$ docker-machine ls
+
 NAME     ACTIVE   DRIVER         STATE     URL                          SWARM   DOCKER        ERRORS
 node-1   -        digitalocean   Running   tcp://104.131.69.233:2376            v17.07.0-ce
 node-2   -        digitalocean   Running   tcp://104.131.115.146:2376           v17.07.0-ce
@@ -41,14 +50,22 @@ node-3   -        digitalocean   Running   tcp://159.203.168.121:2376
 
 Refer to the [documentation](https://docs.docker.com/machine/drivers/digital-ocean/) for more detailed information on the DigitalOcean options for docker-machine.
 
-# Initialize Docker Swarm
+# Create your Docker Swarm
+
+A Docker Swarm can contain as little as a single master node and begins by running the `docker swarm init` command. It's important if you have more than one node that you specify an `--advertise-addr` value.
+
 Intialize Docker Swarm on `node-1`.
+
 ```
-docker-machine ssh node-1 -- docker swarm init --advertise-addr $(docker-machine ip node-1)
+$ docker-machine ssh node-1 -- docker swarm init --advertise-addr $(docker-machine ip node-1)
 ```
-If deploying only `1` node skip to the next section.
 
-If deploying `>1` node take a note of the command to add a worker to the Swarm. 
+> If you opted to deploy a single node, then skip to the next section.
+
+When deploying more than a single Docker host take a note of the command to add a worker to the Swarm. This output contains your *join token*. 
+
+> If you lose it you can get a new one any time with the command: `docker swarm join-token worker` or `manager`.
+
 ```
 Swarm initialized: current node (je5vne1f974fea60ca75q2cac) is now a manager.
 
@@ -61,20 +78,27 @@ To add a manager to this swarm, run 'docker swarm join-token manager' and follow
 
 Add `node-2` to the Swarm, using the `docker swarm join..` command returned when initializing the master.
 ```
-docker-machine ssh node-2 -- docker swarm join --token SWMTKN-1-239v0epdnhuol2ldguttncoaleovy29hnwyglde0kba1owc9ng-9488z5we2invwcn69f5flq7uu 104.131.69.233:2377
+$ docker-machine ssh node-2 -- docker swarm join --token SWMTKN-1-239v0epdnhuol2ldguttncoaleovy29hnwyglde0kba1owc9ng-9488z5we2invwcn69f5flq7uu 104.131.69.233:2377
 ```
+
 Repeat for `node-3`.
+
 ```
-docker-machine ssh node-3 -- docker swarm join --token SWMTKN-1-239v0epdnhuol2ldguttncoaleovy29hnwyglde0kba1owc9ng-9488z5we2invwcn69f5flq7uu 104.131.69.233:2377
+$ docker-machine ssh node-3 -- docker swarm join --token SWMTKN-1-239v0epdnhuol2ldguttncoaleovy29hnwyglde0kba1owc9ng-9488z5we2invwcn69f5flq7uu 104.131.69.233:2377
 ```
 
 ## Configure Docker CLI to use remote Swarm
+
 Run this command each time you open a new shell, this tells Docker where your remote Swarm is.
+
 ```
 eval $(docker-machine env node-1)
 ```
 
 ## Deploy the OpenFaaS Stack
+
+This command clones the OpenFaaS Github repository then checkouts out a stable release before deploying a Docker stack. Docker Swarm will automatically distribute your functions and OpenFaaS services across the cluster.
+
 ```
 $ git clone https://github.com/alexellis/faas && \
   cd faas && \
@@ -83,25 +107,34 @@ $ git clone https://github.com/alexellis/faas && \
 ```
 
 ## Test the UI
+
 Within a few seconds (or minutes if on a poor WiFi connection) the API gateway and sample functions will be deployed to the Swarm cluster running on DigitalOcean.
 
 Access the Gateway UI via the IP address returned by `docker-machine ip node-1` (you can also access via `node-2` and `node-3`):
+
 ```
-echo http://$(docker-machine ip node-1):8080
+$ echo http://$(docker-machine ip node-1):8080
 ```
-Prometheus metrics can be viewed at:
+
+Prometheus metrics can be viewed on port 9090 on a master. Fetch the IP like this:
+
 ```
-echo http://$(docker-machine ip node-1):9090
+$ echo http://$(docker-machine ip node-1):9090
 ```
 
 ## Deleting OpenFaaS Droplets
+
 You can use `docker-machine` to delete any created Droplets if are finished with your OpenFaaS deployment.
+
 ```
 docker-machine rm node-1 node-2 node-3
 ```
 
-## Creating a Load Balancer
-Rather than address each node individually it can be preferrable to run behind a load balancer.
+## Advanced
+
+### Create a Load Balancer
+
+Digital Ocean provide their own *Load Balancers* which mean you only need to share or map one IP address to your DNS records or internal applications. They can also apply health-checks which ensure traffic is only routed to healthy nodes.
 
 From the DigitalOcean console Networking page, open the Load Balancers tab and click *Create Load Balancer*.