docs(GITBOOK#147): Installation Refactor for NoPorts Desktop

atsign-foundation · Dec 19, 2024 · eaecffb · eaecffb
1 parent 34037f4
commit eaecffb
Show file tree

Hide file tree

Showing 52 changed files with 913 additions and 450 deletions.
diff --git a/docs/.gitbook/assets/CleanShot 2024-12-16 at [email protected] b/docs/.gitbook/assets/CleanShot 2024-12-16 at [email protected]
diff --git a/docs/.gitbook/includes/activate-cli-client-unix.md b/docs/.gitbook/includes/activate-cli-client-unix.md
@@ -0,0 +1,19 @@
+---
+title: activate-cli-client-unix
+---
+
+{% hint style="warning" %}
+If you've activated your **client** atSign on another device already, this step will not work. Instead, follow this guide: [reuse-your-client-atsign-on-another-machine.md](../../installation-faq/reuse-your-client-atsign-on-another-machine.md "mention")
+{% endhint %}
+
+This command activates your atSign and prompts you to enter an OTP. This is only done during the setup of a brand new atsign.
+
+```
+~/.local/bin/at_activate -a @<REPLACE>_client
+```
+
+### Enter the One Time Password (OTP) & Check your SPAM/PROMOTIONS folders
+
+at\_activate will pause and wait for the input of a one time pin (OTP) sent to your email or phone number.\
+\
+Once activated, the master keys will save at `~/.atsign/keys`.
diff --git a/docs/.gitbook/includes/activate-cli-device-unix.md b/docs/.gitbook/includes/activate-cli-device-unix.md
@@ -0,0 +1,15 @@
+---
+title: activate-cli-device-unix
+---
+
+This command activates your atSign and prompts you to enter an OTP. This is only done during the setup of a brand new atsign.
+
+```
+~/.local/bin/at_activate -a @<REPLACE>_device
+```
+
+### Enter the One Time Password (OTP) & Check your SPAM/PROMOTIONS folders
+
+at\_activate will pause and wait for the input of a one time pin (OTP) sent to your email or phone number.
+
+Once activated, the management keys will be saved in `~/.atsign/keys`.
diff --git a/docs/.gitbook/includes/apkam-1-unix.md b/docs/.gitbook/includes/apkam-1-unix.md
@@ -0,0 +1,9 @@
+---
+title: apkam-1-unix
+---
+
+Run the following command. It should output a 6-character passcode.
+
+```bash
+~/.local/bin/at_activate otp -a @<REPLACE>_device
+```
diff --git a/docs/.gitbook/includes/apkam-2-unix.md b/docs/.gitbook/includes/apkam-2-unix.md
@@ -0,0 +1,19 @@
+---
+title: apkam-2-unix
+---
+
+<pre class="language-bash"><code class="lang-bash"><strong>~/.local/bin/at_activate enroll -a @&#x3C;REPLACE>_device \
+</strong><strong>  -s &#x3C;PASSCODE> \
+</strong><strong>  -p noports \
+</strong><strong>  -k ~/.atsign/keys/@&#x3C;REPLACE>_device_key.atKeys \
+</strong><strong>  -d &#x3C;DEVICE_NAME> \
+</strong><strong>  -n "sshnp:rw,sshrvd:rw"
+</strong></code></pre>
+
+### Once you see this text, you're ready to continue to the next step.
+
+```
+Submitting enrollment request 
+Enrollment ID: ---------------------
+Waiting for approval; will check every 10 seconds
+```
diff --git a/docs/.gitbook/includes/apkam-3-unix.md b/docs/.gitbook/includes/apkam-3-unix.md
@@ -0,0 +1,11 @@
+---
+title: apkam-3-unix
+---
+
+Run the following command
+
+```bash
+~/.local/bin/at_activate approve -a @<REPLACE>_device \
+  --arx noports \
+  --drx <DEVICE_NAME>
+```
diff --git a/docs/.gitbook/includes/client-installation-complete.md b/docs/.gitbook/includes/client-installation-complete.md
@@ -0,0 +1,7 @@
+---
+title: client-installation complete
+---
+
+{% hint style="success" %}
+Your client machine software installation is completed. Now, on to the device/server!
+{% endhint %}
diff --git a/docs/.gitbook/includes/dart-binary-releases-table.md b/docs/.gitbook/includes/dart-binary-releases-table.md
@@ -0,0 +1,10 @@
+---
+title: Dart Binary Releases Table
+---
+
+| Platform | Linux                                                                                                                | macOS                                                                                                                        | Windows                                                                                                              |
+| -------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| x64      | [sshnp-linux-x64.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-x64.tgz)     | [sshnp-macos-x64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-macos-x64.zip) (intel)     | [sshnp-windows-x64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-windows-x64.zip) |
+| arm64    | [sshnp-linux-arm64.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-arm64.tgz) | [sshnp-macos-arm64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-macos-arm64.zip) (apple) |                                                                                                                      |
+| arm      | [sshnp-linux-arm.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-arm.tgz)     |                                                                                                                              |                                                                                                                      |
+| risc-v   | [sshnp-linux-riscv.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-riscv.tgz) |                                                                                                                              |                                                                                                                      |
diff --git a/docs/.gitbook/includes/desktop-app-release-table.md b/docs/.gitbook/includes/desktop-app-release-table.md
@@ -0,0 +1,5 @@
+---
+title: Desktop App Release Table
+---
+
+<table><thead><tr><th>Operating System</th><th>Download Location</th><th data-hidden></th></tr></thead><tbody><tr><td>Windows</td><td><a href="https://apps.microsoft.com/detail/9n69scrrgv6r">Windows Store</a></td><td></td></tr><tr><td>MacOS</td><td><a href="https://apps.apple.com/ca/app/noports-desktop/id6737338881">App Store</a></td><td></td></tr><tr><td>Linux</td><td><a href="https://github.com/atsign-foundation/noports">Build from Source</a></td><td></td></tr></tbody></table>
diff --git a/docs/.gitbook/includes/device-activate-preamble.md b/docs/.gitbook/includes/device-activate-preamble.md
@@ -0,0 +1,9 @@
+---
+title: device-activate-preamble
+---
+
+{% hint style="info" %}
+Even though this atSign is for the device, we recommend activating it from your client.
+
+More info: [why-activate-the-device-atsign-on-the-client.md](../../installation-faq/why-activate-the-device-atsign-on-the-client.md "mention")
+{% endhint %}
diff --git a/docs/.gitbook/includes/device-warning-setup-client-first.md b/docs/.gitbook/includes/device-warning-setup-client-first.md
@@ -0,0 +1,7 @@
+---
+title: device-warning setup client first
+---
+
+{% hint style="danger" %}
+If you don't already have a NoPorts client setup, start there before setting up the device.
+{% endhint %}
diff --git a/docs/.gitbook/includes/full-install-overview.md b/docs/.gitbook/includes/full-install-overview.md
@@ -0,0 +1,32 @@
+---
+title: full-install-overview
+---
+
+# Overview of the Process
+
+Before you begin, you may want an overview of the guide.
+
+<details>
+
+<summary>&#x3C;- Click the arrow to open the overview</summary>
+
+**Step 1**: Client machine setup
+
+* This process will involve installing the client and activation software on the client machine (1.1 & 1.2)
+* Then we will activate the management keys on your client machine (1.3 & 1.4)
+  * The management keys allow you to administer more keys for other devices and should be kept in a safe place
+
+**Step 2**: Device setup
+
+* This process looks similar to step one, but will be done on the device
+* This step will install the device and activation installer on the device (2.1 & 2.2)
+
+**Step 3**: Activating the device
+
+* Since we created the management keys on the client, we will now authorize a set of keys for the device.
+* These new keys for the device will be cut on the device and have limited access to improve your device's security
+* First we will generate an authorized pass code from the client (3.1)
+* We will use that passcode to generate an authorization request on the device (3.2)
+* Then we will approve the authorization request from the device (3.3)
+
+</details>
diff --git a/docs/.gitbook/includes/get-atsigns-from-reg-warning.md b/docs/.gitbook/includes/get-atsigns-from-reg-warning.md
@@ -0,0 +1,7 @@
+---
+title: get-atsigns-from-reg-warning
+---
+
+{% hint style="danger" %}
+If you don't own a pair of atSigns/addresses, please visit [the registrar](https://my.noports.com/no-ports-invite/14dayfreetrial) before continuing
+{% endhint %}
diff --git a/docs/.gitbook/includes/installation-complete-visit-usage.md b/docs/.gitbook/includes/installation-complete-visit-usage.md
@@ -0,0 +1,9 @@
+---
+title: Installation Complete - visit usage
+---
+
+{% hint style="success" %}
+Installation Complete!\
+\
+You are ready to use No Ports, visit [usage](../../usage/ "mention")!
+{% endhint %}
diff --git a/docs/.gitbook/includes/installation-legend.md b/docs/.gitbook/includes/installation-legend.md
@@ -0,0 +1,9 @@
+---
+title: Installation legend
+---
+
+| Legend     | Meaning                   |
+| ---------- | ------------------------- |
+| :desktop:  | Client side               |
+| :printer:  | Device side               |
+| \<REPLACE> | Fill in with your details |
diff --git a/docs/.gitbook/includes/linux-macos-release-table.md b/docs/.gitbook/includes/linux-macos-release-table.md
@@ -0,0 +1,10 @@
+---
+title: Linux/MacOS release table
+---
+
+| Platform | Linux                                                                                                                | macOS                                                                                                                        |
+| -------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| x64      | [sshnp-linux-x64.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-x64.tgz)     | [sshnp-macos-x64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-macos-x64.zip) (intel)     |
+| arm64    | [sshnp-linux-arm64.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-arm64.tgz) | [sshnp-macos-arm64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-macos-arm64.zip) (apple) |
+| arm      | [sshnp-linux-arm.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-arm.tgz)     |                                                                                                                              |
+| risc-v   | [sshnp-linux-riscv.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-riscv.tgz) |                                                                                                                              |
diff --git a/docs/.gitbook/includes/mac-linux-full-install-video.md b/docs/.gitbook/includes/mac-linux-full-install-video.md
@@ -0,0 +1,5 @@
+---
+title: Mac/Linux full install video
+---
+
+{% embed url="https://player.vimeo.com/video/1004237823?amp;app_id=58479&autopause=0&badge=0&byline=0&player_id=0&portrait=0&title=0" %}
diff --git a/docs/.gitbook/includes/universal.sh-download-command.md b/docs/.gitbook/includes/universal.sh-download-command.md
@@ -0,0 +1,13 @@
+---
+title: universal.sh download command
+---
+
+```bash
+curl -L https://github.com/atsign-foundation/noports/releases/latest/download/universal.sh -o universal.sh
+```
+
+To check if the installation downloaded correctly:
+
+```bash
+ls | grep -w "universal.sh"
+```
diff --git a/docs/.gitbook/includes/universal.sh-execute-activate-only.md b/docs/.gitbook/includes/universal.sh-execute-activate-only.md
@@ -0,0 +1,5 @@
+---
+title: universal.sh execute - activate only
+---
+
+Type in `client` when asked for what type of install. You can either complete the install to have full client support, or press `ctrl + c` when it asks for more information to skip the rest of the client installation.
diff --git a/docs/.gitbook/includes/universal.sh-execute-device-detail.md b/docs/.gitbook/includes/universal.sh-execute-device-detail.md
@@ -0,0 +1,7 @@
+---
+title: universal.sh execute - device detail
+---
+
+The script will guide you through the installation process. It will prompt you for the information you need. Make sure you type in `device` when it asks what type of installation.\
+\
+**You will need the client atSign, device atSign and the device name. making sure they match your earlier choices.**
diff --git a/docs/.gitbook/includes/universal.sh-execute.md b/docs/.gitbook/includes/universal.sh-execute.md
@@ -0,0 +1,10 @@
+---
+title: universal.sh execute
+---
+
+Make the script executable and run the script.
+
+```bash
+chmod u+x universal.sh
+./universal.sh
+```
diff --git a/docs/.gitbook/includes/universal.sh-preamble.md b/docs/.gitbook/includes/universal.sh-preamble.md
@@ -0,0 +1,7 @@
+---
+title: universal.sh preamble
+---
+
+First, make sure that you have [curl](https://curl.se) available on your system, curl is a common shell utility.
+
+The following command will download the `universal.sh` bash installer into your current directory:
diff --git a/docs/.gitbook/includes/unversal.sh-execute-client-details.md b/docs/.gitbook/includes/unversal.sh-execute-client-details.md
@@ -0,0 +1,13 @@
+---
+title: unversal.sh execute - client details
+---
+
+Type in **`client`** when asked for what type of install. Continue following along with the instructions provided with the installer until the installation is complete.
+
+### Useful tips when answering the client installation
+
+Your client atSign should look like : `@sshnp_client`
+
+Your device atSign should look like: `@sshnp_device`
+
+[Device name](../../installation-faq/installation-details.md#device-names) should look like: `my_host, pi3, home_server_2`
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -2,10 +2,18 @@
 
 * [Home](README.md)
 * [Installation](installation/README.md)
-  * [Linux & MacOS Installation Guide](installation/linux/README.md)
-    * [Activating your atSigns](installation/linux/activating-your-atsigns.md)
-    * [Installation Details](installation/linux/installation-details.md)
-  * [Windows Installation Guide](installation/windows.md)
+  * [MacOS Installation Guides](installation/macos/README.md)
+    * [MacOS Desktop Client Installation](installation/macos/desktop.md)
+    * [MacOS CLI Client Installation](installation/macos/cli-client.md)
+    * [MacOS Device Installation](installation/macos/device.md)
+  * [Linux Installation Guide](installation/linux/README.md)
+    * [Linux Full Installation](installation/linux/full.md)
+    * [Linux Cli Client Installation](installation/linux/cli-client.md)
+    * [Linux Device Installation](installation/linux/device.md)
+  * [Windows Installation Guide](installation/windows/README.md)
+    * [Windows Desktop Client Installation](installation/windows/desktop.md)
+    * [Windows CLI Client Installation](installation/windows/cli-client.md)
+    * [Windows Device Installation](installation/windows/device.md)
   * [Manual Installation Guides](installation/advanced-installation-guides/README.md)
     * [Device installation](installation/advanced-installation-guides/device-installation-sshnpd/README.md)
       * [Tmux session](installation/advanced-installation-guides/device-installation-sshnpd/tmux-session.md)
@@ -23,15 +31,21 @@
     * [Automated Installation on Google Cloud Platform (GCP)](installation/cloud-installation-guides/automated-installation-on-google-cloud-platform-gcp.md)
     * [Automated Installation on Microsoft Azure](installation/cloud-installation-guides/automated-installation-on-microsoft-azure.md)
     * [Automated Installation on Oracle Cloud Infrastructure (OCI)](installation/cloud-installation-guides/automated-installation-on-oracle-cloud-infrastructure-oci.md)
+  * [Available Releases](installation/available-releases.md)
   * [Desktop App Installation (MacOS & Windows)](installation/desktop-app-installation-macos-and-windows.md)
+* [Installation FAQ](installation-faq/README.md)
+  * [How to activate an atSign](installation-faq/activating-your-atsigns.md)
+  * [Reuse your client atSign on another machine](installation-faq/reuse-your-client-atsign-on-another-machine.md)
+  * [How to name a device](installation-faq/installation-details.md)
+  * [How to generate SSH keys](installation-faq/how-to-generate-ssh-keys.md)
+  * [Why activate the device atSign on the client?](installation-faq/why-activate-the-device-atsign-on-the-client.md)
 * [Usage](usage/README.md)
   * [npt Usage](usage/basic-usage/README.md)
     * [Additional Configuration](usage/basic-usage/additional-configuration.md)
   * [sshnp Usage](usage/basic-usage-1/README.md)
     * [Client Additional Configuration](usage/basic-usage-1/additional-configuration.md)
   * [sshnpd configuration](usage/sshnpd-configuration/README.md)
     * [Daemon Additional Configuration](usage/sshnpd-configuration/daemon-additional-configuration.md)
-  * [Quick SSH picker script](usage/quick-ssh-picker-script.md)
   * [Integrate with ssh config](usage/integrate-with-ssh-config.md)
 
 ## Use Cases

diff --git a/docs/installation-faq/README.md b/docs/installation-faq/README.md
@@ -0,0 +1,24 @@
+# Installation FAQ
+
+Here are some helpful guides which may aid you if you get stuck during the installation process
+
+{% content-ref url="activating-your-atsigns.md" %}
+[activating-your-atsigns.md](activating-your-atsigns.md)
+{% endcontent-ref %}
+
+{% content-ref url="reuse-your-client-atsign-on-another-machine.md" %}
+[reuse-your-client-atsign-on-another-machine.md](reuse-your-client-atsign-on-another-machine.md)
+{% endcontent-ref %}
+
+{% content-ref url="installation-details.md" %}
+[installation-details.md](installation-details.md)
+{% endcontent-ref %}
+
+{% content-ref url="how-to-generate-ssh-keys.md" %}
+[how-to-generate-ssh-keys.md](how-to-generate-ssh-keys.md)
+{% endcontent-ref %}
+
+{% content-ref url="why-activate-the-device-atsign-on-the-client.md" %}
+[why-activate-the-device-atsign-on-the-client.md](why-activate-the-device-atsign-on-the-client.md)
+{% endcontent-ref %}
+