docs(troubleshooting): add swarm troubleshoot info

docs/source/deployment.rst

@@ -2,9 +2,7 @@
 Deployment
 ==========
 
-Portainer is built to run on Docker and is really simple to deploy.
-
-Portainer deployment scenarios can be executed on any platform unless specified.
+Portainer is built to run on Docker and is really simple to deploy. Portainer deployment scenarios can be executed on any platform unless specified.
 
 Quick start
 ===========
@@ -20,9 +18,10 @@ Voilà, you can now use Portainer by accessing the port 9000 on the server where
 
 Inside a Swarm cluster
 ======================
+Before deploying Portainer inside your Swarm cluster, you should ensure that Docker and your Swarm are configured correctly.
+You can refer to the :ref:`Troubleshooting` section to ensure you have correctly configured your environment.
 
-Use our agent setup to deploy Portainer inside a Swarm cluster.
-
+Following the above, you are ready to deploy Portainer inside a Swarm cluster using using our recommended agent enabled deployment.
 **Note**: This setup will assume that you're executing the following instructions on a Swarm manager node.
 
 ::

docs/source/index.rst

@@ -16,6 +16,7 @@ Contents:
    agent
    external_endpoints
    templates
+   troubleshooting
    contribute
    limitations
    faq

docs/source/troubleshooting.rst

@@ -0,0 +1,45 @@
+===============
+Troubleshooting
+===============
+
+Portainer is built to run on Docker. If Docker is not configured correctly, then this can cause issues that appear to be coming from Portainer.
+
+Ensuring Docker is configured correctly
+=======================================
+
+The first thing to look at whether Docker is actually functioning correctly on your system.
+
+::
+
+  $ docker version
+
+The above command should have returned information about Docker running on your system. Below is a snippet of what this may look like.
+
+.. code-block:: bash
+
+  $ Client: Docker Engine - Community
+      Version:           19.03.3
+      API version:       1.40
+      Go version:        go1.12.10
+      Git commit:        a872fc2f86
+      Built:             Tue Oct  8 00:59:59 2019
+      OS/Arch:           linux/amd64
+      Experimental:      false
+
+Ensuring Docker Swarm is configured correctly
+=============================================
+
+All nodes will require the following ports to be open:
+
+* 7946/tcp
+* 7946/udp
+* 4789/udp
+
+For the manager node:
+
+* 2377/tcp
+
+Next, make sure you are using the ``--advertise-addr`` option.
+
+- When creating the cluster via ``docker swarm init``, use ``--advertise-addr`` with either the private IP address or NIC name directly (``--advertise-addr eth1`` for example)
+- When joining a cluster on worker nodes via ``docker swarm join``, use ``--advertise-addr`` the same as above with either private IP address or NIC name directly