improve doc

README.md

@@ -1,23 +1,33 @@
-# My Sample NodeJS application
+# My OpenShift Demo written in NodeJS
+
+This GitHub repository is my demo that exhibit the main features of OpenShift.
+Feel free to use it to spread the word.
 
 ## Description
 
-TODO
+The demo is a simple application written in NodeJS that is lightweight. It features
+a colored square with an "Hello world from <pod_name>!" in it.
 
-## Setup
+Using this, you can exhibit :
+ - Self-Healing
+ - Scaling
+ - Source-to-Image
+ - CI/CD with Blue/Green Deployment
 
-### In a DEV environment
+## Setup
 
-To deploy the app :
+To deploy the app and start playing with it, just use Source-to-Image :
 ```
 oc new-app nodejs~https://github.com/nmasse-itix/OpenShift-Demo-NodeJS.git --strategy=source
 ```
 
-To cleanup :
+To cleanup your environment, use :
 ```
 oc delete all -l app=openshift-demo-nodejs
 ```
 
-### Full CICD Deployment
+Then, once confident, you can setup a full CI/CD environment as described in the [Installation Guide](doc/INSTALL.md).
+
+## Demo Scenario
 
-See [INSTALL](doc/INSTALL.md).
+Once your environment is setup, you can have a look at the [Demo Scenario](doc/SCENARIO.md).

doc/INSTALL.md

@@ -20,6 +20,10 @@ Deploy a Jenkins in the BUILD project :
 oc new-app -n demo-build --template=jenkins-persistent --name=jenkins -p MEMORY_LIMIT=1Gi
 ```
 
+__Note :__ The `jenkins-persistent` Template requires you to provision a PersistentVolume.
+If there is no available PersistentVolume, the deployment will fail. In this case, have a look to
+my other project : the [OpenShift-Hostpath-Provisioner](https://github.com/nmasse-itix/OpenShift-HostPath-Provisioner).
+
 Create all other objects using the template :
 ```
 oc process -f setup/all-in-one-template.yaml > objects.json
@@ -70,6 +74,10 @@ Deploy a Jenkins in the build project :
 oc new-app -n demo-build --template=jenkins-persistent --name=jenkins -p MEMORY_LIMIT=1Gi
 ```
 
+__Note :__ The `jenkins-persistent` Template requires you to provision a PersistentVolume.
+If there is no available PersistentVolume, the deployment will fail. In this case, have a look to
+my other project : the [OpenShift-Hostpath-Provisioner](https://github.com/nmasse-itix/OpenShift-HostPath-Provisioner).
+
 Give admin role to the jenkins service account on subsequent environments :
 ```
 oc adm policy add-role-to-user admin system:serviceaccount:demo-build:jenkins -n demo-test

doc/SCENARIO.md

@@ -0,0 +1,72 @@
+# Demo Scenario
+
+## Deploy in the DEV environment
+
+In this scenario, we are a developer joining an existing team. This developer
+has to setup his environment and start modifying the application.
+
+Main steps :
+ - Use Source-to-Image to deploy the app (either through CLI or GUI)
+ - Show the running app in the browser
+ - Modify the source code to change the color of the square
+ - Trigger a new build
+ - Show the modified app
+ - Show the container logs
+ - Open a shell in the container and show how to debug
+
+## Deploy in the TEST and PROD environments
+
+In this scenario, we will deploy the new version of the application in the
+TEST and PROD environments. To do so, we will use Jenkins.
+
+Main steps :
+ - Modify the source code (if not already done) to change the color of the square
+ - Show that the TEST and PROD application is running and has the previous color
+ - Trigger the Jenkins pipeline from OpenShift and follow progress
+ - When Jenkins waits for input on the last step, show the TEST app (has the new color)
+ - Show that the PROD app is still on the previous color
+ - In OpenShift, authorize the deployment in the PROD environment
+ - Show that the PROD app has the new color
+
+## Self-Healing in the TEST environment
+
+In this scenario, we will show that OpenShift restart a POD when it crashes or disappear.
+
+Main steps :
+ - In the TEST environment, get the POD Id of the running application
+ - Kill it with `oc delete pod <pod_id>`
+ - Watch the Web GUI, you will see OpenShift starting a new POD
+
+## Scaling in the TEST environment
+
+In this scenario, we will show that you can easily scale your application by starting
+new PODs.
+
+Main steps :
+ - In the TEST environment, click the "up arrow" in the GUI
+ - Watch OpenShift starting a new POD
+ - Once the new POD is ready, show with multiple `curl` that the two PODs are serving requests :
+
+```
+$ curl http://route.to.test.app/info
+{"color":"purple","podName":"openshift-demo-nodejs-2-2mcgb"}
+
+$ curl http://route.to.test.app/info
+{"color":"purple","podName":"openshift-demo-nodejs-2-nsbv6"}
+```
+
+## How to modify the app
+
+To run the previous scenarios, you will have to modify the app to have a different color.
+Here is how to do so.
+
+Main steps :
+ - Edit `server.js` and modify line 7 (`var color = ...`) to have a different color.
+ - You can find nice colors [here](https://www.w3schools.com/cssref/css_colors.asp)
+ - Run the following commands :
+
+```
+git add server.js
+git commit -m 'improve look and feel'
+git push
+```