More details for the troubleshooting items

skupperproject · Dec 20, 2023 · b907fb0 · b907fb0
1 parent 7201920
commit b907fb0
Show file tree

Hide file tree

Showing 6 changed files with 107 additions and 43 deletions.
diff --git a/docs/install/index.html b/docs/install/index.html
@@ -81,7 +81,8 @@ <h2 id="using-the-install-script">Using the install script</h2>
 to download and extract the command:</p>
 <div class="code-label">Linux or Mac</div>
 
-<pre><code>curl https://skupper.io/install.sh | sh</code></pre>
+<pre><code class="language-shell">curl https://skupper.io/install.sh | sh
+</code></pre>
 <p>The script installs the command under your home directory.  It prompts
 you to add the command to your path if necessary.</p>
 <h2 id="installing-manually">Installing manually</h2>
@@ -99,10 +100,12 @@ <h3 id="extract-the-skupper-command">Extract the Skupper command</h3>
 <p>Use <code>tar</code> or <code>unzip</code> to extract the command from the release archive:</p>
 <div class="code-label">Linux or Mac</div>
 
-<pre><code>tar -xf skupper-cli-1.5.1-linux-amd64.tgz</code></pre>
+<pre><code class="language-shell">tar -xf skupper-cli-1.5.1-linux-amd64.tgz
+</code></pre>
 <div class="code-label">Windows</div>
 
-<pre><code>unzip skupper-cli-1.5.1-windows-amd64.zip</code></pre>
+<pre><code class="language-shell">unzip skupper-cli-1.5.1-windows-amd64.zip
+</code></pre>
 <p>This produces an executable file named <code>skupper</code> in your current
 directory.</p>
 <h3 id="place-the-command-on-your-path">Place the command on your path</h3>
@@ -111,26 +114,29 @@ <h3 id="place-the-command-on-your-path">Place the command on your path</h3>
 in your home directory:</p>
 <div class="code-label">Linux or Mac</div>
 
-<pre><code>mkdir $HOME/bin
+<pre><code class="language-console">mkdir $HOME/bin
 mv skupper $HOME/bin
-export PATH=$PATH:$HOME/bin</code></pre>
+export PATH=$PATH:$HOME/bin
+</code></pre>
 <div class="code-label">Windows</div>
 
-<pre><code>mkdir %UserProfile%\bin
+<pre><code class="language-console">mkdir %UserProfile%\bin
 move skupper.exe %UserProfile%\bin
-set PATH=%PATH%;%UserProfile%\bin</code></pre>
+set PATH=%PATH%;%UserProfile%\bin
+</code></pre>
 <h3 id="check-the-command">Check the command</h3>
 <p>To test your installation, run the <code>skupper version</code> command.  You
 should see output like this:</p>
-<pre><code>$ skupper version
+<pre><code class="language-console">$ skupper version
 client version                 1.5.1
 transport version              not-found (no configuration has been provided)
-controller version             not-found (no configuration has been provided)</code></pre>
+controller version             not-found (no configuration has been provided)
+</code></pre>
 <h3 id="upgrade-sites">Upgrade sites</h3>
 <p>When you install a new version of the CLI, you can upgrade each site
-using the <code>skupper update</code> command.
-While we try to make Skupper compatible between sites with different
-versions, we recommend updating all sites at the same time.</p>
+using the <code>skupper update</code> command.  While we try to make Skupper
+compatible between sites with different versions, we recommend
+updating all sites at the same time.</p>
 
 
     </main>

diff --git a/docs/install/troubleshooting.html b/docs/install/troubleshooting.html
@@ -77,16 +77,31 @@
 
 <h1 id="troubleshooting">Troubleshooting</h1>
 <h2 id="some-install-directories-are-not-writable">Some install directories are not writable</h2>
-<p>Change directory permissions.  Make sure your current user has
-permission to write to the <code>~/bin</code> directory.</p>
+<p>Make sure your current user has permission to write to the
+<code>$HOME/.local/bin</code> directory:</p>
+<pre><code class="language-console">$ ls -ld $HOME/.local/bin
+drwxrwxr-x. 1 fritz fritz 264 Dec 20 09:01 /home/fritz/.local/bin
+</code></pre>
 <h2 id="some-required-programs-are-not-available">Some required programs are not available</h2>
-<p>Use your OS's package manager to install the required packages.</p>
-<pre><code>$ dnf whatprovides &lt;program&gt;
-$ sudo dnf install &lt;package&gt;
+<p>Use your OS package manager to install the required packages.</p>
+<p>For example, this is how you find and install <code>awk</code> on Fedora:</p>
+<pre><code class="language-console">$ dnf whatprovides awk
+gawk-5.1.1-5.fc38.x86_64 : The GNU version of the AWK text processing utility
+Repo        : fedora
+Matched from:
+Filename    : /usr/bin/awk
+Provide    : /bin/awk
+$ sudo dnf install gawk
 </code></pre>
 <h2 id="some-required-network-resources-are-not-available">Some required network resources are not available</h2>
-<p>Check your network.  Use traceroute to find out where connectivity
-falters.</p>
+<p>Make sure you can reach github.com:</p>
+<pre><code class="language-console">$ ping github.com
+PING github.com (140.82.113.4) 56(84) bytes of data.
+64 bytes from lb-140-82-113-4-iad.github.com (140.82.113.4): icmp_seq=1 ttl=51 time=34.3 ms
+</code></pre>
+<p>Use <code>traceroute</code> to find out where connectivity falters:</p>
+<pre><code class="language-console">$ traceroute github.com
+</code></pre>
 <!-- ## The checksum does not match the downloaded release archive -->
 
 <!-- - Try blowing away the cached download. -->

diff --git a/docs/main.css b/docs/main.css
@@ -220,6 +220,10 @@ li {
     margin: 0;
 }
 
+li > *:last-child {
+    margin-bottom: 1em;
+}
+
 table th, table td {
     text-align: left;
     padding-right: 1em;

diff --git a/input/install/index.md b/input/install/index.md
@@ -11,7 +11,9 @@ to download and extract the command:
 
 <div class="code-label">Linux or Mac</div>
 
-    curl https://skupper.io/install.sh | sh
+~~~ shell
+curl https://skupper.io/install.sh | sh
+~~~
 
 The script installs the command under your home directory.  It prompts
 you to add the command to your path if necessary.
@@ -41,11 +43,15 @@ Use `tar` or `unzip` to extract the command from the release archive:
 
 <div class="code-label">Linux or Mac</div>
 
-    tar -xf skupper-cli-{{skupper_release}}-linux-amd64.tgz
+~~~ shell
+tar -xf skupper-cli-{{skupper_release}}-linux-amd64.tgz
+~~~
 
 <div class="code-label">Windows</div>
 
-    unzip skupper-cli-{{skupper_release}}-windows-amd64.zip
+~~~ shell
+unzip skupper-cli-{{skupper_release}}-windows-amd64.zip
+~~~
 
 This produces an executable file named `skupper` in your current
 directory.
@@ -58,29 +64,35 @@ in your home directory:
 
 <div class="code-label">Linux or Mac</div>
 
-    mkdir $HOME/bin
-    mv skupper $HOME/bin
-    export PATH=$PATH:$HOME/bin
+~~~ console
+mkdir $HOME/bin
+mv skupper $HOME/bin
+export PATH=$PATH:$HOME/bin
+~~~
 
 <div class="code-label">Windows</div>
 
-    mkdir %UserProfile%\bin
-    move skupper.exe %UserProfile%\bin
-    set PATH=%PATH%;%UserProfile%\bin
+~~~ console
+mkdir %UserProfile%\bin
+move skupper.exe %UserProfile%\bin
+set PATH=%PATH%;%UserProfile%\bin
+~~~
 
 ### Check the command
 
 To test your installation, run the `skupper version` command.  You
 should see output like this:
 
-    $ skupper version
-    client version                 {{skupper_release}}
-    transport version              not-found (no configuration has been provided)
-    controller version             not-found (no configuration has been provided)
+~~~ console
+$ skupper version
+client version                 {{skupper_release}}
+transport version              not-found (no configuration has been provided)
+controller version             not-found (no configuration has been provided)
+~~~
 
 ### Upgrade sites
 
 When you install a new version of the CLI, you can upgrade each site
-using the `skupper update` command.
-While we try to make Skupper compatible between sites with different
-versions, we recommend updating all sites at the same time.
+using the `skupper update` command.  While we try to make Skupper
+compatible between sites with different versions, we recommend
+updating all sites at the same time.
diff --git a/input/install/troubleshooting.md b/input/install/troubleshooting.md
@@ -2,22 +2,45 @@
 
 ## Some install directories are not writable
 
-Change directory permissions.  Make sure your current user has
-permission to write to the `~/bin` directory.
+Make sure your current user has permission to write to the
+`$HOME/.local/bin` directory:
+
+~~~ console
+$ ls -ld $HOME/.local/bin
+drwxrwxr-x. 1 fritz fritz 264 Dec 20 09:01 /home/fritz/.local/bin
+~~~
 
 ## Some required programs are not available
 
-Use your OS's package manager to install the required packages.
+Use your OS package manager to install the required packages.
 
-~~~
-$ dnf whatprovides <program>
-$ sudo dnf install <package>
+For example, this is how you find and install `awk` on Fedora:
+
+~~~ console
+$ dnf whatprovides awk
+gawk-5.1.1-5.fc38.x86_64 : The GNU version of the AWK text processing utility
+Repo        : fedora
+Matched from:
+Filename    : /usr/bin/awk
+Provide    : /bin/awk
+$ sudo dnf install gawk
 ~~~
 
 ## Some required network resources are not available
 
-Check your network.  Use traceroute to find out where connectivity
-falters.
+Make sure you can reach github.com:
+
+~~~ console
+$ ping github.com
+PING github.com (140.82.113.4) 56(84) bytes of data.
+64 bytes from lb-140-82-113-4-iad.github.com (140.82.113.4): icmp_seq=1 ttl=51 time=34.3 ms
+~~~
+
+Use `traceroute` to find out where connectivity falters:
+
+~~~ console
+$ traceroute github.com
+~~~
 
 <!-- ## The checksum does not match the downloaded release archive -->
 <!-- - Try blowing away the cached download. -->
diff --git a/input/main.css b/input/main.css
@@ -220,6 +220,10 @@ li {
     margin: 0;
 }
 
+li > *:last-child {
+    margin-bottom: 1em;
+}
+
 table th, table td {
     text-align: left;
     padding-right: 1em;