docs: Add troubleshooting FAQ and call more attention to local cluster (

#976)

docs/Makefile

@@ -2,7 +2,10 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -W
+#
+# For some reason, the new version of Sphinx treats *.html links
+# as warnings, so we had to disable the -W flag that treats them as errors.
+SPHINXOPTS    = 
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

docs/_build/html/_sources/faq.md.txt

@@ -1,6 +1,39 @@
 Frequently Asked Questions
 ==========================
 
+Troubleshooting
+----------------------------
+
+### Q: I'm getting push errors like "unauthorized: You don't have the needed permissions" when I try to build the [first example](first_example.html). What do I do?
+
+If Tilt is trying to do a push, that means it thinks you wanted to deploy to a
+remote cluster.
+
+The tutorials will only work with a local cluster that doesn't require an image
+push, like Docker For Mac or Minikube.
+
+See [below](faq.html#q-how-do-i-change-what-kubernetes-cluster-tilt-uses) on how
+to configure for a local cluster.
+
+### Q: Tilt fails with "Unable to connect to cluster" errors. What do I do?
+
+The Kubernetes server that you're trying to deploy to is misbehaving.
+
+Two common things to try are:
+
+1) Turn it off and turn it back on again (really!).
+2) Reset the cluster state.
+
+But the specific way to do these depend on your environment.
+
+If you're using Docker For Mac, click the Docker icon in the upper-right hand
+corner of your screen. Choose "Preferences..." to open a dialog. The
+"Kubernetes" tab has a button that allows you to enable/disable Kubernetes. The
+"Reset" tab has a button that allows you to reset the cluster state.
+
+If you're using Minikube, `minikube stop` and `minikube start` will restart the
+environment. `minikube delete` will reset the cluster state.
+
 Building Container Images
 -------------------------
 

docs/_build/html/_sources/first_example.md.txt

@@ -1,12 +1,34 @@
 Running your First Tilt Project
 ===============================
 
-This tutorial assumes you already have `tilt` and its dependencies set up,
-and configured for a local cluster.
+Prerequisites
+-------------
 
-For your first Tilt project, let's not worry about configuring a project just yet.
-Let's look at a simple existing project and see how easy it is to
-`tilt up` and go.
+For this tutorial, you should have:
+
+- [Installed `tilt`](install.html)
+- Configured `kubectl` for a local cluster
+
+To double-check, run:
+
+```
+$ tilt version
+v0.4.2-dev, built 2019-01-09
+$ kubectl config current-context
+docker-for-desktop
+```
+
+If the cluster is NOT `docker-for-desktop` or `minikube`,
+see the FAQ on
+[how to change your cluster](faq.html#q-how-do-i-change-what-kubernetes-cluster-tilt-uses).
+This example will only work with these local clusters.
+
+Starting One Server
+-------------------
+
+For your first Tilt project, let's not worry about configuring a project just
+yet.  Let's look at a simple existing project and see how easy it is to `tilt
+up` and go.
 
 First, check out the Tilt repo.
 
@@ -45,6 +67,11 @@ tilt down
 
 to turn off the server.
 
+Troubleshooting
+---------------
+
+If any of the examples in this tutorial didn't work for you, see the
+[Troubleshooting FAQ](faq.html#Troubleshooting).
 
 Next Steps
 ----------

docs/_build/html/faq.html

@@ -114,6 +114,11 @@
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="code_of_conduct.html">Code of Conduct</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Frequently Asked Questions</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#q-i-m-getting-push-errors-like-unauthorized-you-don-t-have-the-needed-permissions-when-i-try-to-build-the-first-example-what-do-i-do">Q: I’m getting push errors like “unauthorized: You don’t have the needed permissions” when I try to build the first example. What do I do?</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#q-tilt-fails-with-unable-to-connect-to-cluster-errors-what-do-i-do">Q: Tilt fails with “Unable to connect to cluster” errors. What do I do?</a></li>
+</ul>
+</li>
 <li class="toctree-l2"><a class="reference internal" href="#building-container-images">Building Container Images</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="#q-all-the-tilt-examples-store-the-image-at-gcr-io-isn-t-it-really-slow-to-push-images-up-to-google-s-remote-repository-for-local-development">Q: All the Tilt examples store the image at <code class="docutils literal notranslate"><span class="pre">gcr.io</span></code>. Isn’t it really slow to push images up to Google’s remote repository for local development?</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#q-docker-buildkit-is-cool-how-do-i-use-it">Q: Docker Buildkit is cool! How do I use it?</a></li>
@@ -194,6 +199,34 @@
 
   <div class="section" id="frequently-asked-questions">
 <span id="frequently-asked-questions"></span><h1>Frequently Asked Questions<a class="headerlink" href="#frequently-asked-questions" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="troubleshooting">
+<span id="troubleshooting"></span><h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="q-i-m-getting-push-errors-like-unauthorized-you-don-t-have-the-needed-permissions-when-i-try-to-build-the-first-example-what-do-i-do">
+<span id="q-i-m-getting-push-errors-like-unauthorized-you-don-t-have-the-needed-permissions-when-i-try-to-build-the-first-example-what-do-i-do"></span><h3>Q: I’m getting push errors like “unauthorized: You don’t have the needed permissions” when I try to build the <a class="reference external" href="first_example.html">first example</a>. What do I do?<a class="headerlink" href="#q-i-m-getting-push-errors-like-unauthorized-you-don-t-have-the-needed-permissions-when-i-try-to-build-the-first-example-what-do-i-do" title="Permalink to this headline">¶</a></h3>
+<p>If Tilt is trying to do a push, that means it thinks you wanted to deploy to a
+remote cluster.</p>
+<p>The tutorials will only work with a local cluster that doesn’t require an image
+push, like Docker For Mac or Minikube.</p>
+<p>See <a class="reference external" href="faq.html#q-how-do-i-change-what-kubernetes-cluster-tilt-uses">below</a> on how
+to configure for a local cluster.</p>
+</div>
+<div class="section" id="q-tilt-fails-with-unable-to-connect-to-cluster-errors-what-do-i-do">
+<span id="q-tilt-fails-with-unable-to-connect-to-cluster-errors-what-do-i-do"></span><h3>Q: Tilt fails with “Unable to connect to cluster” errors. What do I do?<a class="headerlink" href="#q-tilt-fails-with-unable-to-connect-to-cluster-errors-what-do-i-do" title="Permalink to this headline">¶</a></h3>
+<p>The Kubernetes server that you’re trying to deploy to is misbehaving.</p>
+<p>Two common things to try are:</p>
+<ol class="simple">
+<li>Turn it off and turn it back on again (really!).</li>
+<li>Reset the cluster state.</li>
+</ol>
+<p>But the specific way to do these depend on your environment.</p>
+<p>If you’re using Docker For Mac, click the Docker icon in the upper-right hand
+corner of your screen. Choose “Preferences…” to open a dialog. The
+“Kubernetes” tab has a button that allows you to enable/disable Kubernetes. The
+“Reset” tab has a button that allows you to reset the cluster state.</p>
+<p>If you’re using Minikube, <code class="docutils literal notranslate"><span class="pre">minikube</span> <span class="pre">stop</span></code> and <code class="docutils literal notranslate"><span class="pre">minikube</span> <span class="pre">start</span></code> will restart the
+environment. <code class="docutils literal notranslate"><span class="pre">minikube</span> <span class="pre">delete</span></code> will reset the cluster state.</p>
+</div>
+</div>
 <div class="section" id="building-container-images">
 <span id="building-container-images"></span><h2>Building Container Images<a class="headerlink" href="#building-container-images" title="Permalink to this headline">¶</a></h2>
 <div class="section" id="q-all-the-tilt-examples-store-the-image-at-gcr-io-isn-t-it-really-slow-to-push-images-up-to-google-s-remote-repository-for-local-development">

docs/_build/html/first_config.html

@@ -227,35 +227,35 @@
 <p>This next line reads Kubernetes YAML, gives it a name, creates it in Kubernetes, and sets up a localhost:8100 listener.</p>
 <p>Tilt tracks dependencies; you can edit YAML, Dockerfiles or the Tiltfile and Tilt will automatically rebuild your server.</p>
 <p>At the risk of diving too deep, let’s unpack that YAML file.</p>
-<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">v1</span>
-<span class="l l-Scalar l-Scalar-Plain">kind</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">Namespace</span>
-<span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
-  <span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">tilt-integration</span>
-  <span class="l l-Scalar l-Scalar-Plain">labels</span><span class="p p-Indicator">:</span>
-    <span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">tilt-integration</span>
+<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">apiVersion</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">v1</span>
+<span class="nt">kind</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">Namespace</span>
+<span class="nt">metadata</span><span class="p">:</span>
+  <span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">tilt-integration</span>
+  <span class="nt">labels</span><span class="p">:</span>
+    <span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">tilt-integration</span>
 <span class="nn">---</span>
-<span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">apps/v1</span>
-<span class="l l-Scalar l-Scalar-Plain">kind</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">Deployment</span>
-<span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
-  <span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">oneup</span>
-  <span class="l l-Scalar l-Scalar-Plain">namespace</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">tilt-integration</span>
-  <span class="l l-Scalar l-Scalar-Plain">labels</span><span class="p p-Indicator">:</span>
-    <span class="l l-Scalar l-Scalar-Plain">app</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">oneup</span>
-<span class="l l-Scalar l-Scalar-Plain">spec</span><span class="p p-Indicator">:</span>
-  <span class="l l-Scalar l-Scalar-Plain">selector</span><span class="p p-Indicator">:</span>
-    <span class="l l-Scalar l-Scalar-Plain">matchLabels</span><span class="p p-Indicator">:</span>
-      <span class="l l-Scalar l-Scalar-Plain">app</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">oneup</span>
-  <span class="l l-Scalar l-Scalar-Plain">template</span><span class="p p-Indicator">:</span>
-    <span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
-      <span class="l l-Scalar l-Scalar-Plain">labels</span><span class="p p-Indicator">:</span>
-        <span class="l l-Scalar l-Scalar-Plain">app</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">oneup</span>
-    <span class="l l-Scalar l-Scalar-Plain">spec</span><span class="p p-Indicator">:</span>
-      <span class="l l-Scalar l-Scalar-Plain">containers</span><span class="p p-Indicator">:</span>
-      <span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">oneup</span>
-        <span class="l l-Scalar l-Scalar-Plain">image</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">gcr.io/windmill-test-containers/integration/oneup</span>
-        <span class="l l-Scalar l-Scalar-Plain">command</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">[</span><span class="s">&quot;/go/bin/oneup&quot;</span><span class="p p-Indicator">]</span>
-        <span class="l l-Scalar l-Scalar-Plain">ports</span><span class="p p-Indicator">:</span>
-        <span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">containerPort</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">8000</span>
+<span class="nt">apiVersion</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">apps/v1</span>
+<span class="nt">kind</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">Deployment</span>
+<span class="nt">metadata</span><span class="p">:</span>
+  <span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">oneup</span>
+  <span class="nt">namespace</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">tilt-integration</span>
+  <span class="nt">labels</span><span class="p">:</span>
+    <span class="nt">app</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">oneup</span>
+<span class="nt">spec</span><span class="p">:</span>
+  <span class="nt">selector</span><span class="p">:</span>
+    <span class="nt">matchLabels</span><span class="p">:</span>
+      <span class="nt">app</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">oneup</span>
+  <span class="nt">template</span><span class="p">:</span>
+    <span class="nt">metadata</span><span class="p">:</span>
+      <span class="nt">labels</span><span class="p">:</span>
+        <span class="nt">app</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">oneup</span>
+    <span class="nt">spec</span><span class="p">:</span>
+      <span class="nt">containers</span><span class="p">:</span>
+      <span class="p p-Indicator">-</span> <span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">oneup</span>
+        <span class="nt">image</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">gcr.io/windmill-test-containers/integration/oneup</span>
+        <span class="nt">command</span><span class="p">:</span> <span class="p p-Indicator">[</span><span class="s">&quot;/go/bin/oneup&quot;</span><span class="p p-Indicator">]</span>
+        <span class="nt">ports</span><span class="p">:</span>
+        <span class="p p-Indicator">-</span> <span class="nt">containerPort</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">8000</span>
 </pre></div>
 </div>
 <p>There’s a lot of YAML here! But the idea is easy to summarize: schedule 1 server on Kubernetes.</p>

docs/_build/html/first_example.html

@@ -98,6 +98,9 @@
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="install.html">Tilt Installation Guide</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Running your First Tilt Project</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#starting-one-server">Starting One Server</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#troubleshooting">Troubleshooting</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#next-steps">Next Steps</a></li>
 </ul>
 </li>
@@ -186,11 +189,29 @@
 
   <div class="section" id="running-your-first-tilt-project">
 <span id="running-your-first-tilt-project"></span><h1>Running your First Tilt Project<a class="headerlink" href="#running-your-first-tilt-project" title="Permalink to this headline">¶</a></h1>
-<p>This tutorial assumes you already have <code class="docutils literal notranslate"><span class="pre">tilt</span></code> and its dependencies set up,
-and configured for a local cluster.</p>
-<p>For your first Tilt project, let’s not worry about configuring a project just yet.
-Let’s look at a simple existing project and see how easy it is to
-<code class="docutils literal notranslate"><span class="pre">tilt</span> <span class="pre">up</span></code> and go.</p>
+<div class="section" id="prerequisites">
+<span id="prerequisites"></span><h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2>
+<p>For this tutorial, you should have:</p>
+<ul class="simple">
+<li><a class="reference external" href="install.html">Installed <code class="docutils literal notranslate"><span class="pre">tilt</span></code></a></li>
+<li>Configured <code class="docutils literal notranslate"><span class="pre">kubectl</span></code> for a local cluster</li>
+</ul>
+<p>To double-check, run:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ tilt version
+v0.4.2-dev, built 2019-01-09
+$ kubectl config current-context
+docker-for-desktop
+</pre></div>
+</div>
+<p>If the cluster is NOT <code class="docutils literal notranslate"><span class="pre">docker-for-desktop</span></code> or <code class="docutils literal notranslate"><span class="pre">minikube</span></code>,
+see the FAQ on
+<a class="reference external" href="faq.html#q-how-do-i-change-what-kubernetes-cluster-tilt-uses">how to change your cluster</a>.
+This example will only work with these local clusters.</p>
+</div>
+<div class="section" id="starting-one-server">
+<span id="starting-one-server"></span><h2>Starting One Server<a class="headerlink" href="#starting-one-server" title="Permalink to this headline">¶</a></h2>
+<p>For your first Tilt project, let’s not worry about configuring a project just
+yet.  Let’s look at a simple existing project and see how easy it is to <code class="docutils literal notranslate"><span class="pre">tilt</span> <span class="pre">up</span></code> and go.</p>
 <p>First, check out the Tilt repo.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">windmilleng</span><span class="o">/</span><span class="n">tilt</span>
 <span class="n">cd</span> <span class="n">tilt</span><span class="o">/</span><span class="n">integration</span><span class="o">/</span><span class="n">oneup</span>
@@ -216,6 +237,12 @@
 </pre></div>
 </div>
 <p>to turn off the server.</p>
+</div>
+<div class="section" id="troubleshooting">
+<span id="troubleshooting"></span><h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h2>
+<p>If any of the examples in this tutorial didn’t work for you, see the
+<a class="reference external" href="faq.html#Troubleshooting">Troubleshooting FAQ</a>.</p>
+</div>
 <div class="section" id="next-steps">
 <span id="next-steps"></span><h2>Next Steps<a class="headerlink" href="#next-steps" title="Permalink to this headline">¶</a></h2>
 <p>How did Tilt know how to build the server?