docs: Improve deployment documentation (#304)

- Show how to install Nginx Ingress Controller in README - Document Ingress configuration in chart README - Describe how to access Monocular in NOTES.txt based on various settings
helm · Jun 29, 2017 · 4fb6f1c · 4fb6f1c
1 parent 8364dab
commit 4fb6f1c
Show file tree

Hide file tree

Showing 3 changed files with 64 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -18,16 +18,34 @@ See Monocular in action at [KubeApps.com](https://kubeapps.com) or click [here](
 
 You can use the chart in this repository to install Monocular in your cluster.
 
-##### Prerequisites
+### Prerequisites
 - [Helm and Tiller installed](https://github.com/kubernetes/helm/blob/master/docs/quickstart.md)
-- [Nginx Ingress controller](https://github.com/kubernetes/ingress)
+- [Nginx Ingress controller](https://kubeapps.com/charts/stable/nginx-ingress)
+  - Install with Helm: `helm install stable/nginx-ingress`
+  - **Minikube/Kubeadm**: `helm install stable/nginx-ingress --set controller.hostNetwork=true`
+
 
 ```console
 $ helm repo add monocular https://helm.github.io/monocular
 $ helm install monocular/monocular
 ```
 
-Read more on how to deploy Monocular [here](docs/deployment.md).
+### Access Monocular
+
+Use the Ingress endpoint to access your Monocular instance:
+
+```console
+# Wait for all pods to be running (this can take a few minutes)
+$ kubectl get pods --watch
+
+$ kubectl get ingress
+NAME                        HOSTS     ADDRESS         PORTS     AGE
+tailored-alpaca-monocular   *         192.168.64.30   80        11h
+```
+
+Visit the address specified in the Ingress object in your browser, e.g. http://192.168.64.30.
+
+Read more on how to deploy Monocular [here](deployment/monocular/README.md).
 
 ## Documentation
 

diff --git a/deployment/monocular/README.md b/deployment/monocular/README.md
@@ -84,6 +84,20 @@ EOF
 $ helm install monocular/monocular -f custom-repos.yaml
 ```
 
+### Serve Monocular on a single domain
+
+You can configure the Ingress object with the hostnames you wish to serve Monocular on:
+
+```console
+$ cat > custom-domains.yaml <<<EOF
+ingress:
+  hosts:
+  - monocular.local
+EOF
+
+$ helm install monocular/monocular -f custom-domains.yaml
+```
+
 ### Serve Monocular frontend and API on different domains
 
 In order to serve the frontend and the API on different domains, you need to configure the frontend with the API location and configure CORS correctly for the API to accept requests from the frontend.
@@ -110,10 +124,13 @@ Ensure that you replace `$FRONTEND_HOSTNAME` and `$API_HOSTNAME` with the hostna
 
 ### Other configuration options
 
-| Value                                   | Description                                                                                 | Default               |
-|-----------------------------------------|---------------------------------------------------------------------------------------------|-----------------------|
-| `api.livenessProbe.initialDelaySeconds` | Increase this if the API pods are crashing due to the chart repository sync taking too long | `180`                 |
-| `api.config.releasesEnabled`            | Enable installing and managing charts in the cluster                                        | `3600`                |
-| `api.config.cacheRefreshInterval`       | How often to sync with chart repositories                                                   | `3600`                |
-| `ui.googleAnalyticsId`                  | Google Analytics ID                                                                         | `UA-XXXXXX-X` (unset) |
-| `ui.appName`                            | Name to use in title bar and header                                                         | `Monocular`           |
+| Value                                   | Description                                                                                 | Default                                                                         |
+|-----------------------------------------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
+| `api.livenessProbe.initialDelaySeconds` | Increase this if the API pods are crashing due to the chart repository sync taking too long | `180`                                                                           |
+| `api.config.releasesEnabled`            | Enable installing and managing charts in the cluster                                        | `3600`                                                                          |
+| `api.config.cacheRefreshInterval`       | How often to sync with chart repositories                                                   | `3600`                                                                          |
+| `ui.googleAnalyticsId`                  | Google Analytics ID                                                                         | `UA-XXXXXX-X` (unset)                                                           |
+| `ui.appName`                            | Name to use in title bar and header                                                         | `Monocular`                                                                     |
+| `ingress.enabled`                       | If enabled, create an Ingress object                                                        | `true`                                                                          |
+| `ingress.annotations`                   | Ingress annotations                                                                         | `{ingress.kubernetes.io/rewrite-target: /, kubernetes.io/ingress.class: nginx}` |
+| `ingress.tls`                           | TLS configuration for the Ingress object                                                    | `nil`                                                                           |
diff --git a/deployment/monocular/templates/NOTES.txt b/deployment/monocular/templates/NOTES.txt
@@ -1,5 +1,23 @@
+{{- if eq .Values.ui.backendHostname "/api" -}}
 The Monocular chart sets up an Ingress to serve the API and UI on the same
-domain. You can get the address to access Monocular from this Ingress endpoint.
+domain. You can get the address to access Monocular from this Ingress endpoint:
+
+  $ kubectl get ingress {{ template "fullname" . }}
+
+{{ if ne (join "" .Values.ingress.hosts) "<nil>" -}}
+Point your Ingress hosts to the address from the output of the above command:
+{{ toYaml .Values.ingress.hosts | indent 2 }}
+{{ end -}}
+{{ else -}}
+{{ if not (join "" .Values.api.config.cors.allowed_origins) -}}
+**ERROR**: You have not configured the UI hostname on the server to accept Cross-Origin Resource Sharing requests.
+           See https://github.com/helm/monocular/blob/master/deployment/monocular/README.md#serve-monocular-frontend-and-api-on-different-domains for more information
+{{ else -}}
+
+You can access Monocular on the following domains:
+{{ toYaml .Values.api.config.cors.allowed_origins | indent 2 }}
+{{- end }}
+{{ end -}}
 
 Visit https://github.com/helm/monocular for more information.