Refactor readme following Bitnami best-practices

bitnami/discourse/README.md

@@ -1,44 +1,111 @@
-# Discourse Helm Chart
+# Discourse
 
-> **Note**: This is a Helm 3 chart. Not using Helm 3? Time to upgrade.
+[Discourse](https://www.discourse.org/) is an open source discussion platform. It can be used as a mailing list, discussion forum, long-form chat room, and more.
 
-[Discourse](https://www.discourse.org/) is an opensource forum software.
+## TL;DR;
 
-## Chart Details
-This chart will provision a fully functional and fully featured Discourse installation
-that can deploy and manage applications in the cluster that it is deployed to.
+```console
+$ helm repo add bitnami https://charts.bitnami.com/bitnami
+$ helm install my-release bitnami/discourse
+```
+
+## Introduction
+
+This chart bootstraps a [Discourse](https://www.discourse.org/) deployment on a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager.
+
+It also packages [Bitnami Postgresql](https://github.com/bitnami/charts/tree/master/bitnami/postgresql) and [Bitnami Redis](https://github.com/bitnami/charts/tree/master/bitnami/redis) which are required as a database for the Discourse application.
 
-Redis and Postgres are used.
+Bitnami charts can be used with [Kubeapps](https://kubeapps.com/) for deployment and management of Helm Charts in clusters. This chart has been tested to work with NGINX Ingress, cert-manager, fluentd and Prometheus on top of the [BKPR](https://kubeprod.io/).
 
-For more information on Discourse and its capabilities, see it's [documentation](https://docs.discourse.org/) as well as the [documentation](https://github.com/bitnami/bitnami-docker-discourse#configuration) for the Bitnami Discourse image.
+## Prerequisites
+
+- Kubernetes 1.12+
+- Helm 2.11+ or Helm 3.0-beta3+
+- PV provisioner support in the underlying infrastructure
+- ReadWriteMany volumes for deployment scaling
 
 ## Installing the Chart
 
 To install the chart with the release name `my-release`:
 
-```bash
-$ helm install --name my-release .
+```console
+$ helm install my-release bitnami/discourse
 ```
 
-Discourse is pretty insistent on accessing it via port 80 or 443. This is fine if you're hosting it on a public cluster, but if you want to test it locally with a port forward you need to fight it.
+The command deploys Discourse on the Kubernetes cluster in the default configuration. The [Parameters](#parameters) section lists the parameters that can be configured during installation.
 
-The easiest [but horribly insecure] way to do it it is to simply allow kubectl to bind to privileged ports and then use a `port-forward`:
+> **Tip**: List all releases using `helm list`
 
-```bash
-sudo setcap CAP_NET_BIND_SERVICE=+eip $(which kubectl)
-kubectl portforward svc/discourse 80:3000
+## Uninstalling the Chart
+
+To uninstall/delete the `my-release` deployment:
+
+```console
+$ helm delete my-release
 ```
 
-## Configuration
+The command removes all the Kubernetes components associated with the chart and deletes the release.
+
+## Parameters
+
+The following table lists the configurable parameters of the Discourse chart and their default values.
+
+| Parameter                          | Description                                           | Default                                                      |
+| ---------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
+**TBD after other patches get merged**
 
-Configurable values are documented in the `values.yaml`.
+The above parameters map to the env variables defined in [bitnami/discourse](https://github.com/bitnami/bitnami-docker-discourse). For more information please refer to the [bitnami/discourse](https://github.com/bitnami/bitnami-docker-discourse) image documentation.
 
-Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`.
+Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example,
 
-Alternatively, a YAML file that specifies the values for the parameters can be provided while installing the chart. For example,
+```console
+$ helm install my-release \
+  --set discourseUsername=admin,discoursePassword=password,mariadb.mariadbRootPassword=secretpassword \
+    bitnami/discourse
+```
+
+The above command sets the Discourse administrator account username and password to `admin` and `password` respectively. Additionally, it sets the MariaDB `root` user password to `secretpassword`.
 
-```bash
-$ helm install --name my-release -f values.yaml .
+Alternatively, a YAML file that specifies the values for the above parameters can be provided while installing the chart. For example,
+
+```console
+$ helm install my-release -f values.yaml bitnami/discourse
 ```
 
 > **Tip**: You can use the default [values.yaml](values.yaml)
+
+## Configuration and installation details
+
+### [Rolling VS Immutable tags](https://docs.bitnami.com/containers/how-to/understand-rolling-tags-containers/)
+
+It is strongly recommended to use immutable tags in a production environment. This ensures your deployment does not change automatically if the same tag is updated with a different image.
+
+Bitnami will release a new chart updating its containers if a new version of the main container, significant changes, or critical vulnerabilities exist.
+
+### Local development and binding to port 80
+
+Discourse is pretty insistent on giving access via port 80 or 443.
+This is fine if you're hosting it on a public cluster, but it's not while testing the chart locally.
+The easiest [but horribly insecure] way to do it is to simply allow kubectl to bind to privileged ports and then use a `port-forward`:
+
+```console
+sudo setcap CAP_NET_BIND_SERVICE=+eip $(which kubectl)
+kubectl portforward svc/discourse 80:3000
+```
+
+### Image
+
+The `image` parameter allows specifying which image will be pulled for the chart.
+
+#### Private registry
+
+If you configure the `image` value to one in a private registry, you will need to [specify an image pull secret](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod).
+
+1. Manually create image pull secret(s) in the namespace. See [this YAML example reference](https://kubernetes.io/docs/concepts/containers/images/#creating-a-secret-with-a-docker-config). Consult your image registry's documentation about getting the appropriate secret.
+2. Note that the `imagePullSecrets` configuration value cannot currently be passed to helm using the `--set` parameter, so you must supply these using a `values.yaml` file, such as:
+
+```yaml
+imagePullSecrets:
+  - name: SECRET_NAME
+```
+3. Install the chart