Deployment documentation (helm#158)

* Deployment documentation

* Deployment readme

* Deployment readme

* Deployment readme

* Deployment readme

* Deployment readme

* Add Travis status

* Components

README.md

@@ -1,28 +1,29 @@
 # Monocular
+[![Build
+Status](https://travis-ci.org/helm/monocular.svg?branch=master)](https://travis-ci.org/helm/monocular)
 
-- Under ACTIVE development
-
-Monocular is a search and discovery front end for Helm Charts Repositories. Charts Repositories are collections of curated Kubernetes application definitions.
+Monocular is a part of the Helm project and aims to provide a way to search for and discover apps that have been packaged in Helm
+Charts. Monocular includes a scanning back-end for indexing charts and their metadata and a simple user interface.
 
 A monocular is a single-lensed telescope, and perhaps a twee synonym for the kind of kit that would be useful when inspecting a disordered stack of nautical charts, like a magnifying glass or microscope with a spyglass aesthetic. Its adjectival form suggests a Cyclops, with whom Oddysseus was definitely on familiar terms; and its closest synonym is monocle, a well-worn accoutrement of Victorian Great Britain, surely the greatest of all naval empires. `kubernetes` indeed.
 
 As with The Beatles, some things are better in mono.
 
-Visit [the Helm repository](https://github.com/kubernetes/helm) to learn more about Helm, the package manager for Kubernetes.
+Click [here](docs/about.md) to learn more about Helm, Charts and Kubernetes.
 
-Visit [the Charts repository](https://github.com/kubernetes/charts) to learn more about Charts, the Helm unit of configuration for a Kubernetes application definition.
+## Development
 
-# App Structure
+### App Structure
 
 Monocular comprises a UI front end, and a RESTFul HTTP back end API.
 
-# UI Prerequisites
+#### UI Prerequisites
 
 The UI is an angular 2 client application located in `src/ui/`.
 
 More UI docs are [here](src/ui/README.md).
 
-# API Prerequisites
+#### API Prerequisites
 
 The API is a golang HTTP server located in `src/api/`.
 
@@ -32,7 +33,7 @@ The API is a golang HTTP server located in `src/api/`.
 
 More API docs are [here](src/api/README.md).
 
-# Running a development environment
+### Running a development environment
 
 We leverage [docker](https://www.docker.com) (via `docker-compose`) to provide a multi-tier setup for development.
 
@@ -41,14 +42,18 @@ Running `docker-compose up` from the root directory will expose:
 * API backend endpoint via `http://{your-docker-machine-ip-address}:8080`
 * UI frontend via `http://{your-docker-machine-ip-address}:4200`  
 
-**IMPORTANT**: 
+**IMPORTANT**:
 * If your Docker Machine hostname is different than *localhost*, you need to change
-the `backendHostname` value in the file `src/ui/src/app/config.ts`.
-* Run `docker pull bitnami/angular:2.0.0` OR Run `docker login` which will cache your docker hub credentials. 
-Angular:2.0.0 image is required during `docker-compose up` and docker will search local cache or pull image from docker hub.
+the `backendHostname` value in the file `src/ui/src/app/shared/services/config.service.ts`.
 
 You can restart individual services doing `docker-compose restart api|ui`
 
-# Status of the Project
+## Deploy in Kubernetes
+
+More information on how to deploy your own instance of Monocular in Kubernetes [here](docs/deployment.md).
+
+## Contribute
+
+This project is still under active development, so you'll likely encounter [issues](https://github.com/helm/monocular/issues).
 
-This project is still under active development, so you'll likely encounter [issues](https://github.com/helm/monocular/issues). Please participate by filing issues or contributing a pull request!
+Please participate by filing issues or contributing a pull request!

deployment/README.md

@@ -0,0 +1 @@
+Documentation moved [/docs/deployment.md](/docs/deployment.md)

docs/deployment.md

@@ -0,0 +1,112 @@
+# Deploying Monocular in Kubernetes
+
+## Quickstart
+
+Monocular is packaged as a Helm Chart that can be found in the `/deployment/monocular` directory.
+
+> **Prerequisites**
+>
+> The chart is configured and tested to be used alongside an NGINX Ingress controller. Please be sure that you have a running instance in your cluster before proceeding. More information  [here](https://github.com/kubernetes/ingress/tree/master/controllers/nginx).
+
+Install the chart:
+
+```
+helm install deployment/monocular
+```
+
+Visit [Using Helm](https://github.com/kubernetes/helm/blob/master/docs/using_helm.md) to learn more about how to use Helm.
+
+Once deployed, your application should be available at `https://[nginx-ingress-controller-service-ip]`.
+
+### Chart details
+
+The chart contains 3 tiers and one ingress resource.
+
+#### Components
+
+  * UI: AngularJS web frontend.
+  * API: Golang based backend API.
+  * Prerederer: PhantomJS prerenderer for SEO purposes. More information [here](https://github.com/prerender/prerender).
+
+#### Ingress resource
+
+The chart includes an ingress resource that is configured to route the backend API via `[your-domain]/api` so it can be easily consumed by the UI avoiding any CORS issue or configuration.
+
+You can configure many different settings from hosts, ingress-class to tls options using the `values.yaml` file.
+
+# CI/CD scripts
+
+In the `/deployment` directory you can find a set of convenience scripts helpful in CI/CD setups.
+
+## Deploy for the first time
+
+You can deploy a new release of the operations service
+using the `deploy_install.sh` script.
+
+### Arguments
+
+#### Required
+
+* `API_TAG`: Image tag to be used on the API tier, it will be appended to API_IMAGE
+* `UI_TAG`: Image tag to be used on the API tier. It will be appended to UI_IMAGE
+
+#### Optional
+
+* `API_NAME` (default: `gcr.io/helm-ui/monocular-api`)
+* `UI_NAME` (default: `gcr.io/helm-ui/monocular-ui`)
+* `RELEASE_NAME` (default: `Helm's provided random name`) Helm release
+  name.
+* `VALUES_OVERRIDE` (default: `api.image.repository=${API_IMAGE},api.image.tag=${API_TAG},ui.image.repository=${UI_IMAGE},ui.image.tag=${UI_TAG}`) Helm values to be overridden (`helm install --set $VALUES_OVERRIDE`)
+* `HELM_OPTS` (default: no value) Extra options to be passed to the helm
+  command i.e --dry-run --debug
+
+### Examples
+
+```
+# Deploy the release
+API_TAG=1 UI_TAG=1 ./deploy_install.sh
+
+# Deploy setting the release name
+API_TAG=1 UI_TAG=1 RELEASE_NAME='my_release' ./deploy_install.sh
+
+# Deploy with helm debug and dry-run
+API_TAG=1 UI_TAG=1 HELM_OPTS="--debug --dry-run" ./deploy_install.sh
+
+# Deploy overridding default values
+API_TAG=1 UI_TAG=1\
+ VALUES_OVERRIDE="backend.image.repository=my-image,backend.service.type=LoadBalancer"\
+ ./deploy_install.sh
+```
+
+## Upgrade an existing release
+
+You can upgrade an existing release of the operations service using the `deploy_upgrade.sh` script.
+
+### Arguments
+
+#### Required
+
+* `API_TAG`: Image tag to be used on the API tier, it will be appended to API_IMAGE
+* `UI_TAG`: Image tag to be used on the API tier. It will be appended to UI_IMAGE
+* `RELEASE_NAME`: Helm release name.
+
+#### Optional
+
+* `API_NAME` (default: `gcr.io/helm-ui/monocular-api`)
+* `UI_NAME` (default: `gcr.io/helm-ui/monocular-ui`)
+* `SKIP_UPGRADE_CONFIRMATION` (default: false) Skip the confirmation
+  prompt if an upgrade needs to be performed. Useful for unattended
+  name.
+* `VALUES_OVERRIDE` (default: `api.image.repository=${API_IMAGE},api.image.tag=${API_TAG},ui.image.repository=${UI_IMAGE},ui.image.tag=${UI_TAG}`) Helm values to be overridden (`helm install --set $VALUES_OVERRIDE`)
+* `HELM_OPTS` (default: no value) Extra options to be passed to the helm
+  command i.e --dry-run --debug
+
+### Examples
+
+```
+# Upgrade the release in attended mode
+API_TAG=1 UI_TAG=1 RELEASE_NAME='my_release' ./deploy_upgrade.sh
+
+# Upgrade in unattended mode
+API_TAG=1 UI_TAG=1 RELEASE_NAME='my-release' SKIP_UPGRADE_CONFIRMATION=true ./deploy_upgrade.sh
+```