yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Fix install documentation

Browse Source
This commit is contained in:
Qubasa
2025-02-19 14:23:17 +07:00
parent 8fcc004b68
commit 8ac286bcaf
3 changed files with 34 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/site/getting-started/configure.md
View File

@@ -136,7 +136,7 @@ Adding or configuring a new machine requires two simple steps:
In `./modules/disko.nix`, a simple `ext4` disk partitioning scheme is defined for the Disko module. For more complex disk partitioning setups, In `./modules/disko.nix`, a simple `ext4` disk partitioning scheme is defined for the Disko module. For more complex disk partitioning setups,
refer to the [Disko templates](https://github.com/nix-community/disko-templates) or [Disko examples](https://github.com/nix-community/disko/tree/master/example). refer to the [Disko templates](https://github.com/nix-community/disko-templates) or [Disko examples](https://github.com/nix-community/disko/tree/master/example).
### Step 3 (Optional): Renaming Machine ### (Optional): Renaming Machine
If you wish to name your machine to something else, do the following steps: If you wish to name your machine to something else, do the following steps:
@@ -158,8 +158,10 @@ For renaming jon to your own machine name, you can use the following command:
git mv ./machines/jon ./machines/newname git mv ./machines/jon ./machines/newname
``` ```
### (Optional): Removing a Machine
If you only want to setup a single machine at this point, you can delete `sara` from `flake.nix` as well as from the machines directory: If you only want to setup a single machine at this point, you can delete `sara` from `flake.nix` as well as from the machines directory:
``` ```
git rm -r ./machines/sara git rm -rf ./machines/sara
``` ```

47
docs/site/getting-started/deploy.md
View File

@@ -1,13 +1,7 @@
# Deploy your Clan
Integrating a new machine into your Clan environment is an easy yet flexible process, allowing for a straight forward management of multiple NixOS configurations. Now that you have created a new machine, we will walk through how to install it.
We'll walk you through adding a new computer to your Clan.
## Installing a New Machine
Clan CLI, in conjunction with [nixos-anywhere](https://github.com/nix-community/nixos-anywhere), provides a seamless method for installing NixOS on various machines.
This process involves preparing a suitable hardware and disk partitioning configuration and ensuring the target machine is accessible via SSH.
### Step 0. Prerequisites ### Step 0. Prerequisites
@@ -24,7 +18,7 @@ This process involves preparing a suitable hardware and disk partitioning config
2. Boot the target machine and connect it to a network that makes it reachable from your setup computer. 2. Boot the target machine and connect it to a network that makes it reachable from your setup computer.
=== "**Remote Machines**" === "**Cloud VMs**"
- [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH. - [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH.
- [x] **Machine configuration**: See our basic [configuration guide](./configure.md) - [x] **Machine configuration**: See our basic [configuration guide](./configure.md)
@@ -107,27 +101,22 @@ This process involves preparing a suitable hardware and disk partitioning config
For easy sharing of deployment information via QR code, we highly recommend using [KDE Connect](https://apps.kde.org/de/kdeconnect/). For easy sharing of deployment information via QR code, we highly recommend using [KDE Connect](https://apps.kde.org/de/kdeconnect/).
There are two ways to deploy your machine: There are two ways to deploy your machine:
=== "**Password Auth**"
Run the following command to login over SSH with password authentication
```bash
clan machines install [MACHINE] --target-host <IP> --update-hardware-config nixos-facter
```
=== "**QR Code Auth**"
Using the JSON contents of the QR Code:
```terminal
clan machines install [MACHINE] --json "[JSON]" --update-hardware-config nixos-facter
```
OR using a picture containing the QR code
```terminal
clan machines install [MACHINE] --png [PATH] --update-hardware-config nixos-facter
```
1. **SSH with Password Authentication** === "**Cloud VM**"
Run the following command to install using SSH:
```bash
clan machines install [MACHINE] --target-host <IP> --update-hardware-config nixos-facter
```
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] --update-hardware-config nixos-facter
```
- **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] --update-hardware-config nixos-facter
```
=== "**SSH access**"
Replace `<target_host>` with the **target computers' ip address**: Replace `<target_host>` with the **target computers' ip address**:

19
docs/site/getting-started/installer.md
View File

@@ -1,11 +1,16 @@
# Create an Installer Image # Clan Installer Image for Physical Machines
Our installer image simplifies the process of performing remote installations. To install Clan on physical machines, you need to use our custom installer image. This is necessary for proper installation and operation.
Follow our step-by-step guide to create and transfer this image onto a bootable USB drive. !!! note "Using a Cloud VM?"
If you're using a cloud provider's virtual machine (VM), you can skip this section and go directly to the [Configure Machines](configure.md) step. In this scenario, we automatically use [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to replace the kernel during runtime.
??? info "Why nixos-anywhere Doesn't Work on Physical Hardware?"
nixos-anywhere relies on [kexec](https://wiki.archlinux.org/title/Kexec) to replace the running kernel with our custom one. This method often has compatibility issues with real hardware, especially systems with dedicated graphics cards like laptops and servers, leading to crashes and black screens.
??? info "Reasons for a Custom Install Image"
Our custom install images are built to include essential tools like [nixos-facter](https://github.com/nix-community/nixos-facter) and support for [ZFS](https://wiki.archlinux.org/title/ZFS). They're also optimized to run on systems with as little as 1 GB of RAM, ensuring efficient performance even on lower-end hardware.
!!! 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 ### Step 0. Prerequisites
@@ -40,9 +45,9 @@ Follow our step-by-step guide to create and transfer this image onto a bootable
sudo umount /dev/sdb1 sudo umount /dev/sdb1
``` ```
=== "**Linux OS**" === "**Linux OS**"
### Step 2. Flash Custom Installer ### Step 2. Create a Custom Installer
Using clan flash enables the inclusion of ssh public keys and wifi access points. Using clan flash enables the inclusion of ssh public keys into the image.
It also allows to set language and keymap in the installer image. It also allows to set language and keymap in the installer image.
```bash ```bash