Merge pull request #83 from technosophos/docs/fix-install-instructions

docs(install): fix option 1/option 2 ambiguities

docs/developers.md

@@ -6,11 +6,16 @@ This guide explains how to work on the Kashti codebase.
 
 Begin by cloning this repository with your favorite Git tool.
 
+```console
+$ git clone git@github.com:Azure/kashti.git
+$ cd kashti
+```
+
 Install dependancies and run the app with these commands. 
 
-```
-yarn         #install project dependencies
-yarn start   #start a local server
+```console
+$ yarn         #install project dependencies
+$ yarn start   #start a local server
 ```
 
 (You can use `npm` instead of `yarn` if you prefer.)
@@ -24,7 +29,7 @@ To install in a Kubernetes development cluster, we recommend using the chart.
 If you are running Minikube, you can do a full build of this repo into a Docker
 image:
 
-```
+```console
 $ eval $(minikube docker-env)
 $ yarn docker-build
 $ helm install -n brigade-ui chart/kashti --set brigade.apiServer=http://localhost:7745

docs/install.md

@@ -3,26 +3,29 @@
 This document covers the installation of Kashti into a Kubernetes cluster. Kashti
 developers will find developer-specific documentation in the [Developer Guide](developers.md).
 
+Kashti is a client-side JavaScript application. It makes requests to the Brigade API
+server (which is installed as part of Brigade). **The browser that Kashti is run from
+_must_ have access to the Brigade API server.**
+
 ## Kubernetes Installation
 
 To install the Brigade UI to a Kubernetes cluster:
 
 1. [Install Brigade](https://github.com/Azure/brigade)
 2. Get the IP address or hostname of the Brigade API service. You can often do this with `helm status brigade`
 3. Clone this repo and `cd` into the root of the repo
-3. Install the chart: `helm install chart/kashti --brigade.apiServer=http://IP`, where IP is the
-  IP or hostname of the Brigade API service.
+3. Install the chart: `helm install chart/kashti --brigade.apiServer=http://IP:7745`, where IP is the
+  IP or hostname of the Brigade API service. See Option 1 and Option 2 below to
+  determine which value to put here.
 
-This will make the Kashti user interface usable _inside the cluster_.
+_The address or hostname in `brigade.apiServer` is the location that the browser
+will contact to get information about your projects, builds, and jobs._
 
-Kashti is a client-side JavaScript application. It makes requests to the Brigade API
-server (which is installed as part of Brigade). The browser that Kashti is run from
-_must_ have access to the Brigade API server.
+To access Kashti from a browser outside of a cluster, you have two options at the
+moment:
 
-If you are running the browswer outside of a cluster, you have two options:
-
-- Open a tunnel from the browswer to the destination cluster.
-- Allow outside access to your API and Kashti deployments.
+1. Open a tunnel from the browser to the destination cluster.
+2. Allow outside access to your API and Kashti deployments.
 
 > OAuth2 authentication is on the roadmap, but not yet complete. At this point,
 > opening the service to the outside world will allow unauthenticated access
@@ -47,7 +50,7 @@ Once Brigade is running, you can install Kashti, setting the API server endpoint
 to your localhost.
 
 ```console
-$ helm install -n kashti ./charts/kashti --set brigade.apiServer=localhost:7745
+$ helm install -n kashti ./charts/kashti --set brigade.apiServer=http://localhost:7745
 ```
 
 This will install Kashti, and configure it _specifically for tunneling_. Now you
@@ -57,16 +60,16 @@ and the other to the Brigade API server:
 ```console
 $ kubectl get po | grep brigade-brigade-api | awk '{ print $1 }'
 brigade-brigade-api-559fb8df99-kz5wl
-$kubectl port-forward brigade-brigade-api-559fb8df99-kz5wl 7745 
+$ kubectl port-forward brigade-brigade-api-559fb8df99-kz5wl 7745 
 $ kubectl get po | grep kashti | awk '{ print $1 }'
 kashti-kashti-54bf55b988-dsbhf
 $ kubectl port-forward kashti-kashti-54bf55b988-dsbhf 8080:80 &
 ```
 
 At this point, you have:
 
-- Kashti listening on `http://localhost:8080/brigade-ui`. This is the URL you put in your browser.
-- Brigade API listening on `http://localhost:7745`, with Kashti automatically configed
+- Kashti listening on http://localhost:8080/kashti/. This is the URL you put in your browser.
+- Brigade API listening on http://localhost:7745, with Kashti automatically configed
   to talk to it.
 
 
@@ -89,15 +92,23 @@ For example, to use built-in service load balancers, run these commands:
 $ helm repo add brigade https://azure.github.io/brigade
 $ helm install -n brigade brigade/brigade --set api.service.type=LoadBalancer
 ```
+
+(If your cluster does not support LoadBalancer, look at the Ingress control
+documentation in `helm inspect values brigade/brigade`.)
+
 Now you need to wait until the Brigade API service gets a public IP, and then
 install Kashti
 
 ```
 $ kubectl get --no-headers svc brigade-brigade-api | awk '{ print $4 }'
 10.0.0.77  # Should be a public IP, not like this example
-$ helm install -n kashti ./charts/kashti --set service.type=LoadBalancer --set brigade.apiServer=10.0.0.77
+$ helm install -n kashti ./charts/kashti --set service.type=LoadBalancer \
+  --set brigade.apiServer=http://10.0.0.77:7745
 ```
 
+> You can also use a DNS name for `apiServer` if you have mapped the IP to a
+> name. Note that the browser will have to be able to resolve the name.
+
 Note that (if load balancing is enabled for your cluster), you will now have two
 unsecured endpoints.
 
@@ -108,11 +119,13 @@ endpoint shown by this command:
 $ kubectl get --no-headers svc kashti-kashti | awk '{ print $4 }'
 ```
 
-Thus, your URL will be something like `http://10.21.77.4/brigade-ui`.
+Thus, your URL will be something like `http://10.21.77.4/kashti/`.
 
-## With SSL/TLS
+### With SSL/TLS
+
+If you want to add SSL/TLS to your Kashti setup for additional security, we recommend
+doing this via the standard Kubernetes way.
 
 - Configure TLS/SSL for the Brigade API endpoint and also to the Kashti deployment
   - We recommend using [Kube LEGO](https://github.com/kubernetes/charts/tree/master/stable/kube-lego)
-- Point `brigade.apiServer` to the external hostname or IP (`--brigade.apiServer=https://outside.example.com`)
-
+- Point `brigade.apiServer` to the external hostname or IP (`--brigade.apiServer=https://outside.example.com:7745`)