onepanelio · rushtehrani · Jun 8, 2020 · Jun 5, 2020 · Jun 6, 2020 · Jun 6, 2020
diff --git a/docs/deployment/configuration/tls.md b/docs/deployment/configuration/tls.md
@@ -124,6 +124,17 @@ certManager:
     email: <yourCloudflareEmail@example.com>
 ``` 
 
+:::note
+If your token has an non-alphanumerical character, surround the token with single quotes.
+```yaml
+certManager:
+  cloudflare:
+    apiToken: '<api-token goes here>'
+    email: <yourCloudflareEmail@example.com>
+``` 
+
+:::
+
 ### Google CloudDNS
 
 The flag is `clouddns`, as in 

diff --git a/docs/deployment/public/aks.md b/docs/deployment/public/aks.md
@@ -144,7 +144,7 @@ opctl apply
 ```
 
 :::note
-If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, run `kubectl get pods --all-namespaces` to see if there are any crashing pods.
+If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page.
 :::
 
 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running:
@@ -155,11 +155,21 @@ opctl app status
 
 6. Create an `A` record in your DNS provider based on the instructions above.
 
+:::note
+You should use a wildcard `A` record, for example: `*.example.com` or `*.subdomain.example.com`
+:::
+
 :::tip
-Note that you should use a wildcard `A` record, for example: `*.example.com` or `*.subdomain.example.com`
+If you're waiting for your DNS record to propogate, you can set up a [hosts file](https://en.wikipedia.org/wiki/Hosts_(file)) to quickly test the deployment.
+:::
+
+7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token.
+
+:::note
+If the application is not loading, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page for some steps that can help resolve most issues. If you are still having issues, join our [Slack community](https://join.slack.com/t/onepanel-ce/shared_invite/zt-eyjnwec0-nLaHhjif9Y~gA05KuX6AUg) or open an issue in [GitHub](https://github.com/onepanelio/core/issues).
 :::
 
-7. Use the following command to get your auth token to log into Onepanel:
+8. Use the following command to get your auth token to log into Onepanel:
 
 ```bash
 opctl auth token

diff --git a/docs/deployment/public/eks.md b/docs/deployment/public/eks.md
@@ -119,7 +119,7 @@ opctl apply
 ```
 
 :::note
-If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, run `kubectl get pods --all-namespaces` to see if there are any crashing pods.
+If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page.
 :::
 
 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running:
@@ -130,11 +130,21 @@ opctl app status
 
 6. Create a `CNAME` record in your DNS provider based on the instructions above.
 
+:::note
+You should use a wildcard `CNAME` record, for example: `*.example.com` or `*.subdomain.example.com`
+:::
+
 :::tip
-Note that you should use a wildcard `CNAME` record, for example: `*.example.com` or `*.subdomain.example.com`
+If you're waiting for your DNS record to propogate, you can set up a [hosts file](https://en.wikipedia.org/wiki/Hosts_(file)) to quickly test the deployment.
+:::
+
+7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token.
+
+:::note
+If the application is not loading, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page for some steps that can help resolve most issues. If you are still having issues, join our [Slack community](https://join.slack.com/t/onepanel-ce/shared_invite/zt-eyjnwec0-nLaHhjif9Y~gA05KuX6AUg) or open an issue in [GitHub](https://github.com/onepanelio/core/issues).
 :::
 
-7. Use the following command to get your auth token to log into Onepanel:
+8. Use the following command to get your auth token to log into Onepanel:
 
 ```bash
 opctl auth token

diff --git a/docs/deployment/public/gke.md b/docs/deployment/public/gke.md
@@ -115,7 +115,7 @@ opctl apply
 ```
 
 :::note
-If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, run `kubectl get pods --all-namespaces` to see if there are any crashing pods.
+If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page.
 :::
 
 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running:
@@ -126,11 +126,21 @@ opctl app status
 
 6. Create an `A` record in your DNS provider based on the instructions above.
 
+:::note
+You should use a wildcard `A` record, for example: `*.example.com` or `*.subdomain.example.com`
+:::
+
 :::tip
-Note that you should use a wildcard `A` record, for example: `*.example.com` or `*.subdomain.example.com`
+If you're waiting for your DNS record to propogate, you can set up a [hosts file](https://en.wikipedia.org/wiki/Hosts_(file)) to quickly test the deployment.
+:::
+
+7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token.
+
+:::note
+If the application is not loading, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page for some steps that can help resolve most issues. If you are still having issues, join our [Slack community](https://join.slack.com/t/onepanel-ce/shared_invite/zt-eyjnwec0-nLaHhjif9Y~gA05KuX6AUg) or open an issue in [GitHub](https://github.com/onepanelio/core/issues).
 :::
 
-7. Use the following command to get your auth token to log into Onepanel:
+8. Use the following command to get your auth token to log into Onepanel:
 
 ```bash
 opctl auth token

diff --git a/docs/deployment/troubleshooting/overview.md b/docs/deployment/troubleshooting/overview.md
@@ -0,0 +1,68 @@
+---
+title: Troubleshooting
+sidebar_label: Troubleshooting
+---
+
+This document outlines steps to troubleshoot issues that may arise after initial deployment of Onepanel.
+
+
+## General troubleshooting steps
+
+Once you have setup DNS accordingly but the site isn't showing up or you can't login, double check that you have set up DNS correctly:
+
+```bash
+opctl app status
+```
+
+The command above will return a result similar to the following:
+
+```
+Your deployment is ready.
+
+In your DNS, add an A record for *.sub.example.com and point it to '52.225.33.112'
+Once complete, your application will be running at https://app.sub.example.com
+```
+
+:::note
+Depending on your provider, the `opctl app status` may prompt you to set up a `CNAME` record.
+:::
+
+If you see "Your deployment is ready", double check that your DNS record is correct, then ping the domain in the URL above to confirm it is ready:
+
+```bash
+$ ping app.sub.example.com
+PING app.sub.example.com (52.225.33.112) 56(84) bytes of data.
+```
+
+If you see "Not all required pods are running. Your deployment is not ready.", run the following command:
+
+```bash
+kubectl get pods -A
+```
+
+For `Pending` pods, check the `Age`, if it has been less than 5 minutes, wait and check again.
+
+If the pods are showing `Error` or have been in `Pending` state for more than 5 minutes, check the pod in more details by running `kubectl describe` for more details. You can also check the pod log by running `kubectl logs`. 
+
+In most cases, pods stuck in `Pending` state could mean that you need to add another node to your cluster.
+
+
+## Troubleshooting deployments with cert-manager
+Onepanel uses [cert-manager](https://cert-manager.io/) to automatically manages TLS certificates when you install Onepanel with the following flags:
+
+```bash
+opctl init ... --enable-cert-manager --dns-provider <provider>
+```
+
+All cert-manager resources in Onepanel are installed in the `istio-system` namespace.
+
+If you have enabled cert-manager and your application after following [General troubleshooting steps](#general-troubleshooting-steps), then you're most likely running into certificate issues.
+
+You can troubleshoot these issues by following the steps in [Troubleshooting Issuing ACME Certificates](https://cert-manager.io/docs/faq/acme/). Make sure to run all the commands in the `istio-system` namespace. For example to get the certificate that Onepanel uses:
+
+```bash
+kubectl describe certificate cert-manager-wildcard-certificate -n istio-system
+```
+
+## Still having issues?
+Join our [Slack community](https://join.slack.com/t/onepanel-ce/shared_invite/zt-eyjnwec0-nLaHhjif9Y~gA05KuX6AUg) or open an issue in [GitHub](https://github.com/onepanelio/core/issues).
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
@@ -200,7 +200,7 @@ opctl apply
 ```
 
 :::note
-If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, run `kubectl get pods --all-namespaces` to see if there are any crashing pods.
+If the command completes but it indicates that your cluster is not ready, you can check status again by running `opctl app status`. If you're still seeing issues, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page.
 :::
 
 5. Once the deployment completes, the CLI will display the IP and wildcard domain you need to use to setup your DNS. You can also get this information again by running:
@@ -211,7 +211,15 @@ opctl app status
 
 6. Create the appropriate DNS record in your DNS provider based on the instructions above.
 
-7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a token screen as showng below:
+:::tip
+If you don't have a domain name handy or you're waiting for your DNS record to propogate, you can set up a [hosts file](https://en.wikipedia.org/wiki/Hosts_(file)) to quickly test the deployment.
+:::
+
+7. Wait a few minutes and check the URL mentioned in the instructions above. Your applications should load with a screen prompting you to enter a token.
+
+:::note
+If the application is not loading, visit our [Troubleshooting](/docs/deployment/troubleshooting/overview) page for some steps that can help resolve most issues. If you are still having issues, join our [Slack community](https://join.slack.com/t/onepanel-ce/shared_invite/zt-eyjnwec0-nLaHhjif9Y~gA05KuX6AUg) or open an issue in [GitHub](https://github.com/onepanelio/core/issues).
+:::
 
 8. Use the following command to get your auth token to log into Onepanel:
 

diff --git a/sidebars.js b/sidebars.js
@@ -90,6 +90,10 @@ module.exports = {
         'deployment/configuration/files',
         'deployment/configuration/tls',
       ]
+    },
+    { 
+      type: 'doc',
+      id: 'deployment/troubleshooting/overview'
     }
   ],
   reference: [