Merge branch 'add_troubleshooting_doc' into 'master'

Add troubleshooting doc

See merge request openappstack/openappstack!129

docs/index.rst

@@ -30,3 +30,4 @@ For more information, go to `the OpenAppStack website`_.
    testing_instructions
    design
    reference
+   troubleshooting

docs/troubleshooting.md

+# Troubleshooting
+
+Note: `cluster$` indicates that the commands should be run as root on your OAS cluster.
+
+## HTTPS Certificates
+
+OAS uses [cert-manager](http://docs.cert-manager.io/en/latest/) to automatically
+fetch [Let's Encrypt](https://letsencrypt.org/) certificates for all deployed
+services. If you experience invalid SSL certificates (i.e. your browser warns you
+when visiting Nextcloud (`https://files.YOUR.CLUSTER.DOMAIN`) here's how to
+debug this:
+
+Did you create your cluster using the `--acme-live-environment` argument ?
+Please check the resulting value of the `acme_staging` key in
+`clusters/YOUR_CLUSTERNAME/settings.yml`. If this is set to `true`, certificates
+are fetched from the [Let's Encrypt staging API](https://letsencrypt.org/docs/staging-environment/),
+which can't be validated by default in your browser.
+
+Are all pods in the `cert-manager` namespace in the `READY` state ?
+
+    cluster$ kubectl -n cert-manager get pods
+
+Show the logs of the main `cert-manager` pod:
+
+    cluster$ kubectl -n cert-manager logs -l "app.kubernetes.io/name=cert-manager"
+
+You can `grep` for your cluster domain or for any specific subdomain to narrow
+down results.
+
+
+## Purge OAS and install from scratch
+
+If ever things fail beyond possible recovery, here's how to completely purge an OAS installation in order to start from scratch:
+
+    cluster$ apt purge docker-ce-cli containerd.io
+    cluster$ mount | egrep '^(tmpfs.*kubelet|nsfs.*docker)' | cut -d' ' -f 3 | xargs umount
+    cluster$ rm -rf /var/lib/docker /var/lib/OpenAppStack /etc/kubernetes /var/lib/etcd /var/lib/rancher /var/lib/kubelet /var/log/OpenAppStack /var/log/containers /var/log/pods