Merge pull request #6 from gesiscss/docs

improve docs

README.md

@@ -1,7 +1,8 @@
 # Persistent BinderHub
 
 This is a Helm chart to install a persistent BinderHub. 
-It simply extends [BinderHub chart](https://github.com/jupyterhub/binderhub) to bring persistent storage feature. 
+It simply configures and extends [BinderHub chart](https://github.com/jupyterhub/binderhub) to add persistent storage, 
+it doesn't define any new component. 
 Therefore before using this chart it is required that you read through [BinderHub documentation](https://binderhub.readthedocs.io/en/latest/), 
 you know how to deploy a [standard BinderHub](http://mybinder.org/) 
 and you are familiar with [enabling authentication](https://binderhub.readthedocs.io/en/latest/authentication.html) in BinderHub.
@@ -50,19 +51,18 @@ binderhub:
 
 ### Authentication
 
-This chart already includes almost all required changes for 
+This chart already includes some of the required changes for 
 [enabling authentication](https://binderhub.readthedocs.io/en/latest/authentication.html#enabling-authentication). 
 But there are pieces that have to be manually configured. In your `config.yaml`:
 
-1. You have to enter the url of your BinderHub into `oauth_redirect_uri`, and set `oauth_client_id`:
+1. You have to set `oauth_client_id`:
 
 ```bash
 binderhub:
   jupyterhub:
     hub:
       services:
         binder:
-          oauth_redirect_uri: "http://<binderhub_url>/oauth_callback"
           # this is the default value
           oauth_client_id: "binder-oauth-client-test"
 ```
@@ -78,8 +78,18 @@ binderhub:
     auth: {}
 ```
 
+Note that by default the authenticator is [DummyAuthenticator](https://github.com/jupyterhub/dummyauthenticator) 
+and it is recommended to use it only for testing purposes. 
+
 ## Installing the chart
 
+First of all you can find the list of charts here: 
+https://gesiscss.github.io/persistent_binderhub/
+
+The installation consists of 2 steps. As a first step we install the chart, 
+then we will finalize the configuration of the Binder service 
+and upgrade the chart to apply final changes in the config.
+
 To install the chart with the release name `pbhub` into namespace `pbhub-ns`:
 
 ```bash
@@ -101,7 +111,38 @@ helm search persistent_binderhub
 
 ```
 
-Here you can find the list of charts: https://gesiscss.github.io/persistent_binderhub/
+After the first step, run `kubectl get service proxy-public --namespace=$NAMESPACE` 
+and copy the IP address under `EXTERNAL-IP`, which is the IP of the JupyterHub. 
+Then run `kubectl get service binder --namespace=$NAMESPACE` 
+and again copy the IP address under `EXTERNAL-IP`, which is the IP of the Binder service. 
+
+With the IP addresses you just acquired update your `config.yaml`:
+
+```bash
+binderhub:
+  jupyterhub:
+    hub:
+      services:
+        binder:
+          # where binder runs
+          url: "http://<Binder_IP>"
+          # when url is set, binder can be reached through JupyterHub
+          oauth_redirect_uri: "http://<JupyterHub_IP>/services/binder/oauth_callback"
+```
+
+Finally upgrade the chart to apply this change:
+
+```bash
+helm upgrade $RELEASENAME persistent_binderhub/persistent_binderhub --version=0.2.0-n181 \
+             --install --namespace=$NAMESPACE \
+             --debug
+```
+
+When the installation is done, 
+the persistent BinderHub will be available at "http://<JupyterHub_IP>", 
+and there (at JupyterHub home page) you will see a customized BinderHub UI for persistence, 
+which is the place that users will interact with the system mostly.  
+The standard BinderHub will be available at "http://<JupyterHub_IP>/services/binder" as a service of JupyterHub. 
 
 ## Uninstalling the chart