doc update (#68)

* doc update

* Update README.md

Author: sherl0cks

README.md

@@ -1,24 +1,45 @@
-# Open Innovation Labs CI/CD Bootstrapping
-This branch has a reduced subset of Red Hat Open Innovation Labs CI/CD components. We're in the process of refactoring this approach - pardon the mess and lack of documentation.
+# Open Innovation Labs CI/CD
 
-## Overview - Current State
-This is an ansible inventory which identifies a list of applications, including CI / CD components, to be deployed to an OpenShift cluster. The ansible layer is very thin. It simply provides a way to orchestrate the application of [OpenShift templates](https://docs.openshift.com/container-platform/3.6/dev_guide/templates.html) across one or more [OpenShift projects](https://docs.openshift.com/container-platform/3.6/architecture/core_concepts/projects_and_users.html#projects). All configuration for the applications should be defined by an OpenShift template and the corresponding parameters file. 
+The goal of this repository is to:
+
+ 1. provide all the tools necessary for a comprehensive CI/CD pipeline, built for and deployed to OpenShift
+ 2. serve as a reference implementation of the [openshift-applier](https://github.com/redhat-cop/casl-ansible/tree/master/roles/openshift-applier) model for Infrastructure-as-Code (IaC) 
+
+A few additional guiding principles:
+
+* This repository is built as a monolith i.e. all the individual components are designed to be deployed together. When adding a new tool, care should be taken to integrate that tool with the other tools. 
+* To deploy a subset of components, you can:
+  * Use the tags provided in the inventory to filter certain components. See [the docs](https://github.com/redhat-cop/casl-ansible/tree/master/roles/openshift-applier#filtering-content-based-on-tags) in openshift-applier
+  * _coming soon_ - Use the provided tooling to generate a new inventory with a user defined subset of components
+* Generally speaking, there should only be one tool per functional use case e.g. Sonatype Nexus is the artifact repository so we will not support JFrog Artifactory
+
+## How it Works
+
+There is ansible inventory which identifies all components to be deployed to an OpenShift cluster. The ansible layer is very thin. It simply provides a way to orchestrate the application of [OpenShift templates](https://docs.openshift.com/container-platform/3.6/dev_guide/templates.html) across one or more [OpenShift projects](https://docs.openshift.com/container-platform/3.6/architecture/core_concepts/projects_and_users.html#projects). All configuration for the applications should be defined by an OpenShift template and the corresponding parameters file. 
 
 Currently, the following components are included in this inventory:
 
-* Long lived CI/CD, Development and Demo projects 
+* Long lived CI/CD, Development and Demo OpenShift projects 
 * Jenkins, including
   * S2I build for Jenkins plugins and configuration
   * maven and npm slaves for Jenkins
 * Sonatype Nexus
+* SonarQube
 * Example Java application and pipeline
 
+Currently, the following components have templates but are not yet integrated into the inventory:
+
+* Gitlab
+* Gogs
+
 ## Prerequisites
+
 * [Ansible](http://docs.ansible.com/ansible/latest/intro_installation.html)
 * [OpenShift CLI Tools](https://docs.openshift.com/container-platform/3.6/cli_reference/get_started_cli.html)
 * Access to the OpenShift cluster 
 
 ## Usage 
+
 1. Log on to an OpenShift server `oc login -u <user> https://<server>:<port>/`
     1. Your user needs permissions to deploy ProjectRequest objects
 2. Clone this repository
@@ -30,7 +51,7 @@ Currently, the following components are included in this inventory:
 After running the playbook, the pipeline should execute in Jenkins, build the spring boot app, deploy artifacts to nexus, deploy the container to the dev stage and then wait approval to deploy to the demo stage. See Common Issues
 
 
-## Running a Subset of the Inventory
+## Running a Subset of the Inventory 
 
 See [the docs](https://github.com/redhat-cop/casl-ansible/tree/master/roles/openshift-applier#filtering-content-based-on-tags) in casl-ansible
 
@@ -45,7 +66,7 @@ See [the docs](https://github.com/redhat-cop/casl-ansible/tree/master/roles/open
 ## Common Issues
 
 - S2I Build fails to push image to registry with `error: build error: Failed to push image: unauthorized: authentication required`
-  - This appears to be an eventual consistency error. Wait a minute or two and then kick the build off again, it should work
+  - See [this issue](https://github.com/openshift/origin/issues/4518)
 
 ## License
-[ASL 2.0](LICENSE)
+[ASL 2.0](LICENSE)