From 86ae7cbbfb09da50d8f0a3f9ebefcd3d725f9558 Mon Sep 17 00:00:00 2001 From: Qubasa Date: Fri, 10 May 2024 22:59:45 +0200 Subject: [PATCH] Reorder getting started documentation --- docs/mkdocs.yml | 8 +-- docs/site/getting-started/configure.md | 33 ++++------- docs/site/getting-started/installer.md | 28 +++++----- docs/site/getting-started/machines.md | 74 +++++++++++++------------ docs/site/getting-started/networking.md | 2 +- docs/site/getting-started/secrets.md | 17 ++++-- docs/site/index.md | 6 -- 7 files changed, 81 insertions(+), 87 deletions(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a2ce50a86..3bcc6ebd7 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -40,11 +40,11 @@ exclude_docs: | nav: - Getting started: - index.md - - Configure: getting-started/configure.md - - Deploy Machine: getting-started/machines.md - Installer: getting-started/installer.md - - Setup Networking: getting-started/networking.md - - Provision Secrets & Passwords: getting-started/secrets.md + - Configure: getting-started/configure.md + - Secrets & Facts: getting-started/secrets.md + - Deploy Machine: getting-started/machines.md + - Mesh VPN: getting-started/networking.md - Backup & Restore: getting-started/backups.md - Flake-parts: getting-started/flake-parts.md - Templates: templates/index.md diff --git a/docs/site/getting-started/configure.md b/docs/site/getting-started/configure.md index d63804cf4..9f3ade625 100644 --- a/docs/site/getting-started/configure.md +++ b/docs/site/getting-started/configure.md @@ -84,7 +84,7 @@ Adding or configuring a new machine requires two simple steps: === "**buildClan**" - ```nix title="clan-core.lib.buildClan" hl_lines="17 13" + ```nix title="clan-core.lib.buildClan" hl_lines="17" buildClan { # ... machines = { @@ -97,8 +97,8 @@ Adding or configuring a new machine requires two simple steps: # Change this to the correct ip-address or hostname # The hostname is the machine name by default - clan.networking.targetHost = pkgs.lib.mkDefault "root@" - + clan.networking.targetHost = pkgs.lib.mkDefault "root@jon" + # Change this to the ID-LINK of the desired disk shown by 'lsblk' disko.devices.disk.main = { device = "/dev/disk/by-id/__CHANGE_ME__"; @@ -106,15 +106,13 @@ Adding or configuring a new machine requires two simple steps: # ... }; - }; + }; } ``` === "**flakeParts**" - - - ```nix title="clan-core.flakeModules.default" hl_lines="17,13" + ```nix title="clan-core.flakeModules.default" hl_lines="17" clan = { # ... machines = { @@ -127,8 +125,8 @@ Adding or configuring a new machine requires two simple steps: # Change this to the correct ip-address or hostname # The hostname is the machine name by default - clan.networking.targetHost = pkgs.lib.mkDefault "root@" - + clan.networking.targetHost = pkgs.lib.mkDefault "root@jon" + # Change this to the ID-LINK of the desired disk shown by 'lsblk' disko.devices.disk.main = { device = "/dev/disk/by-id/__CHANGE_ME__"; @@ -136,14 +134,14 @@ Adding or configuring a new machine requires two simple steps: # ... }; - }; + }; }; ``` -### Step 2. Detect hardware specific drivers -!!! Tip - If you need to connect the `nixos-image` installer to the wifi, look [here](https://docs.clan.lol/getting-started/installer/#optional-connect-to-wifi). +!!! Info "In this case `__CHANGE_ME__` should be `nvme-eui.e8238fa6bf530001001b448b4aec2929`" + +### Step 2. Detect hardware specific drivers 1. Generate a `hardware-configuration.nix` for your target computer @@ -151,18 +149,11 @@ Adding or configuring a new machine requires two simple steps: ssh root@flash-installer.local nixos-generate-config --no-filesystems --show-hardware-config > machines/jon/hardware-configuration.nix ``` -### Initialize the facts - -!!! Info - **All facts are automatically initialized.** - -If you need additional help see our [facts chapter](./secrets.md) --- ## Whats next? -- [Deploying](machines.md): Deploying a Machine configuration -- [Secrets](secrets.md): Learn about secrets and facts +- [Secrets & Facts](secrets.md): Setting up secrets with nix-sops --- diff --git a/docs/site/getting-started/installer.md b/docs/site/getting-started/installer.md index 04fae71a6..b6a74be29 100644 --- a/docs/site/getting-started/installer.md +++ b/docs/site/getting-started/installer.md @@ -1,10 +1,11 @@ # Installer -We offer a dedicated installer to assist remote installations. +Our installer image simplifies the process of performing remote installations. -In this tutorial we will guide you through building and flashing it to a bootable USB drive. +Follow our step-by-step guide to create and transfer this image onto a bootable USB drive. -## Creating and Using the **Clan Installer** +!!! info + If you already have a NixOS machine you can ssh into (in the cloud for example) you can skip this chapter and go directly to [Configure Machines](configure.md). ### Step 0. Prerequisites @@ -21,7 +22,7 @@ In this tutorial we will guide you through building and flashing it to a bootabl lsblk ``` - ```{.console, .no-copy} + ```shellSession hl_lines="2" NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS sdb 8:0 1 117,2G 0 disk └─sdb1 8:1 1 117,2G 0 part /run/media/qubasa/INTENSO @@ -89,17 +90,6 @@ Select `NixOS` to boot into the clan installer. For deploying your configuration the machine needs to be connected via LAN (recommended). -For connecting via Wifi, please consult the [guide below](#optional-connect-to-wifi). - ---- - -## Whats next? - -- [Configure Machines](configure.md): Customize machine configuration -- [Deploying](machines.md): Deploying a Machine configuration -- [WiFi](#optional-connect-to-wifi): Guide for connecting to Wifi. - ---- ## (Optional) Connect to Wifi @@ -147,3 +137,11 @@ Press `ctrl-d` to exit `IWD`. Press `ctrl-d` **again** to update the displayed QR code and connection information. You're all set up + +--- + +## Whats next? + +- [Configure Machines](configure.md): Customize machine configuration + +--- \ No newline at end of file diff --git a/docs/site/getting-started/machines.md b/docs/site/getting-started/machines.md index 361aabb92..cd24cbdd5 100644 --- a/docs/site/getting-started/machines.md +++ b/docs/site/getting-started/machines.md @@ -35,28 +35,11 @@ This process involves preparing a suitable hardware and disk partitioning config - Any cloud machine if it is reachable via SSH and supports `kexec`. -Confirm the machine is reachable via SSH from your setup computer. - -```bash -ssh root@ -``` ### Step 1. Deploy the machine **Finally deployment time!** Use the following command to build and deploy the image via SSH onto your machine. -=== "**SSH access**" - - - - Replace `` with the **target computers' ip address**: - - ```bash - clan machines install my-machine - ``` - - !!!note - Building and deploying time will depend on hardware and connection speed. === "**Image Installer**" @@ -121,35 +104,50 @@ ssh root@ 4. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted text__, images, ... basically anything that can be written in Markdown. - !!!tip - We recommend using KDE Connect for sharing the deployment information from the QR code with the deploying machine. + For easy sharing of deployment information via QR code, we highly recommend using [KDE Connect](https://apps.kde.org/de/kdeconnect/). - - The QR code can be used to deploy either with an image, that is decoded on the fly, or it's contained json information. + There are two ways to deploy your machine: - With the path to a `json` string, or the string itself: - ```terminal - clan machines install [MACHINE] --json [JSON] - ``` - With the path to an image containing the relevant QR code: - ```terminal - clan machines install [MACHINE] --png [PATH] + 1. **SSH with Password Authentication** + Run the following command to install using SSH: + ```bash + clan machines install [MACHINE] flash-installer.local + ``` + + 2. **Scanning a QR Code for Installation Details** + You can input the information by following one of these methods: + - **Using a JSON String or File Path:** + Provide the path to a JSON string or input the string directly: + ```terminal + clan machines install [MACHINE] --json [JSON] + ``` + - **Using an Image Containing the QR Code:** + Provide the path to an image file containing the relevant QR code: + ```terminal + clan machines install [MACHINE] --png [PATH] + ``` + + !!!note + If you are using our template `[MACHINE]` would be `jon` + +=== "**SSH access**" + + Replace `` with the **target computers' ip address**: + + ```bash + clan machines install [MACHINE] ``` + !!!note + Building and deploying time will depend on hardware and connection speed. + !!! success Your machine is all set up. 🎉 🚀 ---- -## What's next ? - -- [**Update a Machine**](#update-your-machines): Learn how to update an existing machine? -- [**Configure a Private Network**](./networking.md): Configuring a secure mesh network. - ---- ## Update Your Machines @@ -204,6 +202,12 @@ This is useful for machines that are not always online or are not part of the re --- +## What's next ? + +- [**Mesh VPN**](./networking.md): Configuring a secure mesh network. + +--- + # TODO: * TODO: How to join others people zerotier * `services.zerotier.joinNetworks = [ "network-id" ]` diff --git a/docs/site/getting-started/networking.md b/docs/site/getting-started/networking.md index cd7aaaee7..1c3c3f0c9 100644 --- a/docs/site/getting-started/networking.md +++ b/docs/site/getting-started/networking.md @@ -1,4 +1,4 @@ -# Overlay Networks +# Mesh VPN This guide provides detailed instructions for configuring [ZeroTier VPN](https://zerotier.com) within Clan. Follow the diff --git a/docs/site/getting-started/secrets.md b/docs/site/getting-started/secrets.md index df06ccd71..e770552d5 100644 --- a/docs/site/getting-started/secrets.md +++ b/docs/site/getting-started/secrets.md @@ -6,7 +6,6 @@ Clan utilizes the [sops](https://github.com/getsops/sops) format and integrates This documentation will guide you through managing secrets with the Clan CLI -## Initializing Secrets (Quickstart) ### Create Your Master Keypair @@ -52,17 +51,17 @@ sops/ └── / └── key.json ``` +If you followed the quickstart tutorial all necessary secrets are initialized at this point. --- -> If you followed the quickstart tutorial all necessary secrets are initialized at this point. +## Whats next? -- Continue with [deploying machines](./machines.md) -- Learn about the [basics concept](#concept) of clan secrets +- [Deployment](machines.md): How to remotely deploy your machine --- -## Concept +## Indepth Explanation The secrets system conceptually knows two different entities: @@ -325,3 +324,11 @@ Each member of the group `admins` in this case will be able to decrypt the secre Since our clan secret module will auto-import secrets that are encrypted for a particular nixos machine, you can now remove `sops.secrets. = { };` unless you need to specify more options for the secret like owner/group of the secret file. + +--- + +## Whats next? + +- [Deployment](machines.md): How to remotely deploy your machine + +--- diff --git a/docs/site/index.md b/docs/site/index.md index 529353543..551f2e7bc 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -110,12 +110,6 @@ sara ### What's Next? -- [**Machine Configuration**](getting-started/configure.md): Declare behavior and configuration of machines. - -- [**Deploy Machines**](getting-started/machines.md): Learn how to deploy to any remote machine. - - [**Installer**](getting-started/installer.md): Setting up new computers remotely is easy with an USB stick. -- [**Check out our Templates**](templates/index.md) - ---