Restructure documentation for Apple

* Rename docs/ios-client.md to docs/apple-client.md. Add instructions for macOS; those are copied from the /apple endpoint and slightly modified. Fix doc links in the README. * Move infoboxes for /apple and /windows under the "Goal" section to the top. Those should be seen by users first as they contain *their* specific headscale URL. * Swap order of macOS and iOS to move "Profiles" further down. * Remove apple configuration profiles * Remove Tailscale versions hints * Mention /apple and /windows in the README along with their docs See: juanfont#2096
nblock · Sep 9, 2024 · 05d9419 · 05d9419
1 parent 7be8796
commit 05d9419
Show file tree

Hide file tree

Showing 7 changed files with 112 additions and 130 deletions.
diff --git a/README.md b/README.md
@@ -62,15 +62,15 @@ buttons available in the repo.
 
 ## Client OS support
 
-| OS      | Supports headscale                                        |
-| ------- | --------------------------------------------------------- |
-| Linux   | Yes                                                       |
-| OpenBSD | Yes                                                       |
-| FreeBSD | Yes                                                       |
-| macOS   | Yes (see `/apple` on your headscale for more information) |
-| Windows | Yes [docs](./docs/windows-client.md)                      |
-| Android | Yes [docs](./docs/android-client.md)                      |
-| iOS     | Yes [docs](./docs/iOS-client.md)                          |
+| OS      | Supports headscale                                                                                 |
+| ------- | -------------------------------------------------------------------------------------------------- |
+| Linux   | Yes                                                                                                |
+| OpenBSD | Yes                                                                                                |
+| FreeBSD | Yes                                                                                                |
+| Windows | Yes (see [docs](./docs/windows-client.md) and `/windows` on your headscale for more information)   |
+| Android | Yes (see [docs](./docs/android-client.md))                                                         |
+| macOS   | Yes (see [docs](./docs/apple-client.md#macos) and `/apple` on your headscale for more information) |
+| iOS     | Yes (see [docs](./docs/apple-client.md#ios) and `/apple` on your headscale for more information)   |
 
 ## Running headscale
 

diff --git a/docs/apple-client.md b/docs/apple-client.md
@@ -0,0 +1,51 @@
+# Connecting an Apple client
+
+## Goal
+
+This documentation has the goal of showing how a user can use the official iOS and macOS [Tailscale](https://tailscale.com) clients with `headscale`.
+
+!!! info "Instructions on your headscale instance"
+
+    An endpoint with information on how to connect your Apple device
+    is also available at `/apple` on your running instance.
+
+## iOS
+
+### Installation
+
+Install the official Tailscale iOS client from the [App Store](https://apps.apple.com/app/tailscale/id1470499037).
+
+### Configuring the headscale URL
+
+- Open Tailscale and make sure you are _not_ logged in to any account
+- Open Settings on the iOS device
+- Scroll down to the `third party apps` section, under `Game Center` or `TV Provider`
+- Find Tailscale and select it
+  - If the iOS device was previously logged into Tailscale, switch the `Reset Keychain` toggle to `on`
+- Enter the URL of your headscale instance (e.g `https://headscale.example.com`) under `Alternate Coordination Server URL`
+- Restart the app by closing it from the iOS app switcher, open the app and select the regular sign in option
+  _(non-SSO)_. It should open up to the headscale authentication page.
+- Enter your credentials and log in. Headscale should now be working on your iOS device.
+
+## macOS
+
+### Installation
+
+Choose one of the available [Tailscale clients for macOS](https://tailscale.com/kb/1065/macos-variants) and install it.
+
+### Configuring the headscale URL
+
+#### Command line
+
+Use Tailscale's login command to connect with your headscale instance (e.g `https://headscale.example.com`):
+
+```
+tailscale login --login-server <YOUR_HEADSCALE_URL>
+```
+
+#### GUI
+
+- ALT + Click the Tailscale icon in the menu and hover over the Debug menu
+- Under `Custom Login Server`, select `Add Account...`
+- Enter the URL of your headscale instance (e.g `https://headscale.example.com`) and press `Add Account`
+- Follow the login procedure in the browser
diff --git a/docs/iOS-client.md b/docs/iOS-client.md
diff --git a/docs/windows-client.md b/docs/windows-client.md
@@ -4,17 +4,17 @@
 
 This documentation has the goal of showing how a user can use the official Windows [Tailscale](https://tailscale.com) client with `headscale`.
 
+!!! info "Instructions on your headscale instance"
+
+    An endpoint with information on how to connect your Windows device
+    is also available at `/windows` on your running instance.
+
 ## Installation
 
 Download the [Official Windows Client](https://tailscale.com/download/windows) and install it.
 
 ## Configuring the headscale URL
 
-!!! info "Instructions on your headscale instance"
-
-    An endpoint with information on how to connect your Windows device
-    is also available at `/windows` on your running instance.
-
 Open a Command Prompt or Powershell and use Tailscale's login command to connect with your headscale instance (e.g
 `https://headscale.example.com`):
 

diff --git a/hscontrol/templates/apple.html b/hscontrol/templates/apple.html
@@ -25,65 +25,59 @@
   </head>
 
   <body>
-    <h1>headscale: macOS configuration</h1>
-    <h2>Recent Tailscale versions (1.34.0 and higher)</h2>
-    <p>
-      Tailscale added Fast User Switching in version 1.34 and you can now use
-      the new login command to connect to one or more headscale (and Tailscale)
-      servers. The previously used profiles does not have an effect anymore.
-    </p>
-    <h3>Command line</h3>
-    <p>Use Tailscale's login command to add your profile:</p>
-    <pre><code>tailscale login --login-server {{.URL}}</code></pre>
-    <h3>GUI</h3>
+    <h1>headscale: iOS configuration</h1>
+    <h2>GUI</h2>
     <ol>
       <li>
-        ALT + Click the Tailscale icon in the menu and hover over the Debug menu
+        Install the official Tailscale iOS client from the
+        <a href="https://apps.apple.com/app/tailscale/id1470499037"
+          >App store</a
+        >
       </li>
-      <li>Under "Custom Login Server", select "Add Account..."</li>
       <li>
-        Enter "{{.URL}}" of the headscale instance and press "Add Account"
+        Open Tailscale and make sure you are <i>not</i> logged in to any account
       </li>
-      <li>Follow the login procedure in the browser</li>
-    </ol>
-    <h2>Apple configuration profiles (1.32.0 and lower)</h2>
-    <p>
-      This page provides
-      <a href="https://support.apple.com/guide/mdm/mdm-overview-mdmbf9e668/web"
-        >configuration profiles</a
-      >
-      for the official Tailscale clients for
-    </p>
-    <ul>
+      <li>Open Settings on the iOS device</li>
       <li>
-        <a href="https://apps.apple.com/app/tailscale/id1475387142"
-          >macOS - AppStore Client</a
-        >.
+        Scroll down to the "third party apps" section, under "Game Center" or
+        "TV Provider"
       </li>
       <li>
-        <a href="https://pkgs.tailscale.com/stable/#macos"
-          >macOS - Standalone Client</a
-        >.
+        Find Tailscale and select it
+        <ul>
+          <li>
+            If the iOS device was previously logged into Tailscale, switch the
+            "Reset Keychain" toggle to "on"
+          </li>
+        </ul>
       </li>
-    </ul>
-    <p>
-      The profiles will configure Tailscale.app to use <code>{{.URL}}</code> as
-      its control server.
-    </p>
-    <h3>Caution</h3>
-    <p>
-      You should always download and inspect the profile before installing it:
-    </p>
-    <ul>
+      <li>Enter "{{.URL}}" under "Alternate Coordination Server URL"</li>
       <li>
-        for app store client: <code>curl {{.URL}}/apple/macos-app-store</code>
+        Restart the app by closing it from the iOS app switcher, open the app
+        and select the regular sign in option <i>(non-SSO)</i>. It should open
+        up to the headscale authentication page.
       </li>
       <li>
-        for standalone client: <code>curl {{.URL}}/apple/macos-standalone</code>
+        Enter your credentials and log in. Headscale should now be working on
+        your iOS device
       </li>
-    </ul>
+    </ol>
+    <h1>headscale: macOS configuration</h1>
+    <h2>Command line</h2>
+    <p>Use Tailscale's login command to add your profile:</p>
+    <pre><code>tailscale login --login-server {{.URL}}</code></pre>
+    <h2>GUI</h2>
+    <ol>
+      <li>
+        ALT + Click the Tailscale icon in the menu and hover over the Debug menu
+      </li>
+      <li>Under "Custom Login Server", select "Add Account..."</li>
+      <li>
+        Enter "{{.URL}}" of the headscale instance and press "Add Account"
+      </li>
+      <li>Follow the login procedure in the browser</li>
+    </ol>
     <h2>Profiles</h2>
-    <h3>macOS</h3>
     <p>
       Headscale can be set to the default server by installing a Headscale
       configuration profile:
@@ -121,50 +115,17 @@ <h3>macOS</h3>
       </li>
     </ul>
     <p>Restart Tailscale.app and log in.</p>
-    <h1>headscale: iOS configuration</h1>
-    <h2>Recent Tailscale versions (1.38.1 and higher)</h2>
+    <h3>Caution</h3>
     <p>
-      Tailscale 1.38.1 on
-      <a href="https://apps.apple.com/app/tailscale/id1470499037">iOS</a>
-      added a configuration option to allow user to set an "Alternate
-      Coordination server". This can be used to connect to your headscale
-      server.
+      You should always download and inspect the profile before installing it:
     </p>
-    <h3>GUI</h3>
-    <ol>
-      <li>
-        Install the official Tailscale iOS client from the
-        <a href="https://apps.apple.com/app/tailscale/id1470499037"
-          >App store</a
-        >
-      </li>
-      <li>
-        Open Tailscale and make sure you are <i>not</i> logged in to any account
-      </li>
-      <li>Open Settings on the iOS device</li>
-      <li>
-        Scroll down to the "third party apps" section, under "Game Center" or
-        "TV Provider"
-      </li>
-      <li>
-        Find Tailscale and select it
-        <ul>
-          <li>
-            If the iOS device was previously logged into Tailscale, switch the
-            "Reset Keychain" toggle to "on"
-          </li>
-        </ul>
-      </li>
-      <li>Enter "{{.URL}}" under "Alternate Coordination Server URL"</li>
+    <ul>
       <li>
-        Restart the app by closing it from the iOS app switcher, open the app
-        and select the regular sign in option <i>(non-SSO)</i>. It should open
-        up to the headscale authentication page.
+        for app store client: <code>curl {{.URL}}/apple/macos-app-store</code>
       </li>
       <li>
-        Enter your credentials and log in. Headscale should now be working on
-        your iOS device
+        for standalone client: <code>curl {{.URL}}/apple/macos-standalone</code>
       </li>
-    </ol>
+    </ul>
   </body>
 </html>
diff --git a/integration/scenario_test.go b/integration/scenario_test.go
@@ -7,7 +7,7 @@ import (
 )
 
 // This file is intended to "test the test framework", by proxy it will also test
-// some Headcsale/Tailscale stuff, but mostly in very simple ways.
+// some Headscale/Tailscale stuff, but mostly in very simple ways.
 
 func IntegrationSkip(t *testing.T) {
 	t.Helper()

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -139,5 +139,5 @@ nav:
           - Remote CLI: remote-cli.md
       - Usage:
           - Android: android-client.md
+          - Apple: apple-client.md
           - Windows: windows-client.md
-          - iOS: iOS-client.md