Merge pull request #2562 from mboersma/could-not-find-unit

Add "could not find unit template" section to troubleshooting docs

Author: mboersma

docs/troubleshooting_deis/index.rst

@@ -108,28 +108,45 @@ Note that store-volume requires CoreOS >= 471.1.0 for the CephFS kernel module.
 Any component fails to start
 ----------------------------
 
-Use `deisctl status <component>` to view the status of the component.
-You can also use `deisctl journal <component>` to tail logs for a component, or `deisctl list`
+Use ``deisctl status <component>`` to view the status of the component.
+You can also use ``deisctl journal <component>`` to tail logs for a component, or ``deisctl list``
 to list all components.
 
 Failed initializing SSH client
 ------------------------------
 
-A `deisctl` command fails with: 'Failed initializing SSH client: ssh: handshake failed: ssh: unable to authenticate'.
-Did you remember to add your SSH key to the ssh-agent? `ssh-add -L` should list the key you used
-to provision the servers. If it's not there, `ssh-add -K /path/to/your/key`.
+A ``deisctl`` command fails with: 'Failed initializing SSH client: ssh: handshake failed: ssh: unable to authenticate'.
+Did you remember to add your SSH key to the ssh-agent? ``ssh-add -L`` should list the key you used
+to provision the servers. If it's not there, ``ssh-add -K /path/to/your/key``.
 
 All the given peers are not reachable
 -------------------------------------
 
-A `deisctl` command fails with: 'All the given peers are not reachable (Tried to connect to each peer twice and failed)'.
-The most common cause of this issue is that a [new discovery URL](https://discovery.etcd.io/new)
-wasn't generated and updated in `contrib/coreos/user-data` before the cluster was launched.
-Each Deis cluster must have a unique discovery URL, or else `etcd` will try and fail to connect to old hosts.
-Try destroying the cluster and relaunching the cluster with a fresh discovery URL.
+A ``deisctl`` command fails with: 'All the given peers are not reachable (Tried to connect to each peer twice and failed)'.
+The most common cause of this issue is that a new discovery URL wasn't generated and updated in
+``contrib/coreos/user-data`` before the cluster was launched. Each Deis cluster must have a unique
+discovery URL, or else ``etcd`` will try and fail to connect to old hosts. Try destroying the cluster
+and relaunching the cluster with a fresh discovery URL.
 
 You can use ``make discovery-url`` to automatically fetch a new discovery URL.
 
+Could not find unit template...
+-------------------------------
+
+If you built ``deisctl`` locally or didn't use its installer, you may see an error like this:
+
+    .. code-block:: console
+
+        $ deisctl install platform
+
+        Storage subsystem...
+        Could not find unit template for store-daemon
+
+This is because ``deisctl`` could not find unit files for Deis locally. Run
+``deisctl help refresh-units`` to see where ``deisctl`` searches, and then run a command such as
+``deisctl refresh-units --tag=v1.0.1``, or set the ``$DEISCTL_UNITS`` environment variable to a directory
+containing the unit files.
+
 Other issues
 ------------
 
@@ -138,4 +155,3 @@ Running into something not detailed here? Please `open an issue`_ or hop into #d
 .. _`Ceph FS`: https://ceph.com/docs/giant/cephfs/
 .. _`open an issue`: https://github.com/deis/deis/issues/new
 .. _`troubleshooting`: http://docs.ceph.com/docs/giant/rados/troubleshooting/
-