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

docs: improve tutorials

Browse Source
This commit is contained in:
Johannes Kirschbauer
2024-04-10 11:11:22 +02:00
parent f7a29ebaf8
commit adfdc96b64
4 changed files with 286 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/admins/install-iso.md
View File

@@ -19,6 +19,7 @@ nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
1. Insert your USB flash drive into your computer.
2. Identify your flash drive with `lsblk`.
```shellSession
$ lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
@@ -27,7 +28,7 @@ nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
nvme0n1 259:0 0 1,8T 0 disk
├─nvme0n1p1 259:1 0 512M 0 part /boot
└─nvme0n1p2 259:2 0 1,8T 0 part
└─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0 0 1,8T 0 crypt /nix/store /
└─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0 0 1,8T 0 crypt /nix/store
```
In this case it's `sdb`
@@ -48,8 +49,6 @@ Use the `dd` utility to write the NixOS installer image to your USB drive:
In case your USB device is `sdb` use `of=/dev/sdb`
### Boot and Connect
After writing the installer to the USB drive, use it to boot the target machine.
@@ -72,7 +71,8 @@ After writing the installer to the USB drive, use it to boot the target machine.
3. Save your settings. Put in the USB stick and reboot.
4. Press one of keys outlined below to go into the Boot Menu
4. Press one of keys outlined below to go into the Boot Menu
- **Dell**: F12 (Boot Menu)
- **HP**: F9 (Boot Menu)
- **Lenovo**: F12 (ThinkPad Boot Menu)
@@ -85,41 +85,55 @@ After writing the installer to the USB drive, use it to boot the target machine.
- **Apple**: Option (Alt) Key (Boot Menu for Mac)
- If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup.
5. Select `NixOS` to boot into the clan installer
6. The installer will display an IP address and a root password, which you can use to connect via SSH.
Alternatively you can also use the displayed QR code.
7. Set your keyboard language. Important for writing passwords correctly.
```bash
loadkeys de
```
8. If you only have Wifi available, execute:
1. Bring up the `iwd` shell
```bash
iwctl
```
2. List available networks. Double press tab after station for autocompleting your wlan device. In this case `wlan0`
2. List available networks. Double press tab after station for device autocompletion. In this case `wlan0` is the only network wifi device.
```shellSession
[iwd] station wlan0 get-networks
```
3. Connect to a Wifi network. Replace `SSID` with the wlan network name.
```shellSession
[iwd] station wlan0 connect SSID
```
9. Now that you have internet re-execute the init script by pressing `Ctrl+D` or by executing:
```bash
bash
```
10. Connect to the machine over ssh
```bash
ssh-copy-id -o PreferredAuthentications=password root@<ip>
```
Use the root password displayed on your screen as login.
---
# Whats next?
- Deploy a clan machine-configuration on your prepared machine
---

230
docs/admins/machines.md
View File

@@ -1,6 +1,6 @@
# Managing NixOS Machines with Clan
# 01 Managing NixOS Machines with Clan
Integrating a new machine into your Clan environment is a very easy yet flexible process, allowing for the centralized management of multiple NixOS configurations.
Integrating a new machine into your Clan environment is a very easy yet flexible process, allowing for a straight forward management of multiple NixOS configurations.
We'll walk you through adding a new computer to your Clan using a special tool that works through a USB stick.
@@ -90,10 +90,210 @@ The installer will display an IP address and a root password, which you can use
Alternatively you can also use the displayed QR code.
> Note: If your target machine is **accessible via SSH and runs NixOS**; You can skip preparing and booting from the USB stick.
>
> Use the clan CLI command (`clan machines install <my-machine> <target_host>`) to install your configuration remotely via SSH.
#### Prepare the USB Flash Drive
1. Insert your USB flash drive into your computer.
2. Identify your flash drive with `lsblk`
```shellSession
$ lsblk
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
nvme0n1 259:0 0 1,8T 0 disk
├─nvme0n1p1 259:1 0 512M 0 part /boot
└─nvme0n1p2 259:2 0 1,8T 0 part
└─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0 0 1,8T 0 crypt /nix/store /
```
In this case it's `sdb`
3. Ensure all partitions on the drive are unmounted. Replace `sdb1` in the command below with your device identifier (like `sdc1`, etc.):
```bash
sudo umount /dev/sdb1
```
> Note: Repeat this command for all mounted partitions of your USB drive listed under `MOUNTPOINTS`.
## Creating a Bootable USB Drive on Linux
To create a bootable USB flash drive with the NixOS installer:
### Step 1. Build the Installer Image
```bash
nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
```
### Step 2. Write the Image to the USB Drive
Use the `dd` utility to write the NixOS installer image to your USB drive:
```bash
sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sd<X>
```
> [!Note]:
> depending on your device speed this may take a couple of minutes
In case your USB device is `sdb` use `of=/dev/sdb`
### Step 3. Boot and Connect
After writing the installer to the USB drive, use it to boot the target machine.
> i.e. Plug it into the target machine and select the USB drive as a temporary boot device.
For most hardware you can find the Key-combination below:
- **Dell**: F12 (Boot Menu), F2/Del (BIOS Setup)
- **HP**: F9 (Boot Menu), Esc (Startup Menu)
- **Lenovo**: F12 (ThinkPad Boot Menu), F2/Fn+F2/Novo Button (IdeaPad Boot Menu/BIOS Setup)
- **Acer**: F12 (Boot Menu), F2/Del (BIOS Setup)
- **Asus**: F8/Esc (Boot Menu), F2/Del (BIOS Setup)
- **Toshiba**: F12/F2 (Boot Menu), Esc then F12 (Alternate Method)
- **Sony**: F11/Assist Button (Boot Menu/Recovery Options)
- **Samsung**: F2/F12/Esc (Boot Menu), F2 (BIOS Setup)
- **MSI**: F11 (Boot Menu), Del (BIOS Setup)
- **Apple**: Option (Alt) Key (Boot Menu for Mac)
- If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup.
**During Boot**
Select `NixOS` to boot into the clan installer
**After Booting**
The installer will display an IP address and a root password, which you can use to connect via SSH.
Alternatively you can also use the displayed QR code.
To be reachable the machine needs to be connected via LAN (recommended)
If you're using Wifi. Follow the next steps
#### Connect to a Wifi
```bash
iwctl
```
This will enter `iwd`
```bash
[iwd]#
```
Inside IWD run the following command to connect to your Wifi:
```bash
# Identify your network device.
device list
# Replace 'wlan0' with your device name
# Find your Wifi SSID.
station wlan0 scan
station wlan0 get-networks
# Replace your_ssid with the Wifi SSID
# Connect to your network.
station wlan0 connect your_ssid
# Verify you are connected
station wlan0 show
```
If the connection was successful you should see something like this:
```bash
State connected
Connected network FRITZ!Box (Your router device)
IPv4 address 192.168.188.50 (Your new local ip)
```
Use `ctrl-c` or `ctrl-d` to exit `IWD`
The displayed QR code and connection information get updated automatically, once your are connected.
VUG8n9yq0gDHy0zX
### Step 4. Finishing the installation
> IMPORTANT: Now use your main computer
Confirm the machine is reachable via SSH from your other computer.
```bash
ssh root@192.168.188.50
```
> Note:
> Currently in networks where the Router blocks DNS you cannot use the hostname and must use the ip address directly.
> We recommend to deploy using home/private-networks (i.e. FRITZ!Box / Corporate LAN).
> public-networks (i.e. university / airport / cafe) might not always work as expected.
```bash
lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
# Should print something like:
NAME ID-LINK FSTYPE SIZE MOUNTPOINT
sda usb-ST_16GB_AA6271026J1000000509-0:0 14.9G
├─sda1 usb-ST_16GB_AA6271026J1000000509-0:0-part1 1M
├─sda2 usb-ST_16GB_AA6271026J1000000509-0:0-part2 vfat 100M /boot
└─sda3 usb-ST_16GB_AA6271026J1000000509-0:0-part3 ext4 2.9G /
nvme0n1 nvme-eui.e8238fa6bf530001001b448b4aec2929 476.9G
├─nvme0n1p1 nvme-eui.e8238fa6bf530001001b448b4aec2929-part1 vfat 512M
├─nvme0n1p2 nvme-eui.e8238fa6bf530001001b448b4aec2929-part2 ext4 459.6G
└─nvme0n1p3 nvme-eui.e8238fa6bf530001001b448b4aec2929-part3 swap 16.8G
```
Now change the following lines of your configuration you want to deploy.
We need to set the hardware specific `disk-id`
```nix
# flake.nix / configuration.nix
clan.diskLayouts.singleDiskExt4 = {
device = "/dev/disk/by-id/nvme-eui.e8238fa6bf530001001b448b4aec2929";
}
```
Also set the targetHost: (in our case: user `root` hostname `jon`)
```nix
clan.networking.targetHost = pkgs.lib.mkDefault "root@jon"
```
With the target machine running Linux and accessible via SSH, execute the following command to install NixOS on the target machine, replacing `<target_host>` with the machine's hostname or IP address:
Before running the command make sure to `cd` into your `clan`
```bash
my-clan (main)> tree
.
├── flake.lock
├── flake.nix
└── machines
└── jon
└── configuration.nix
```
And verify the machine is detected from `clan CLI`
```bash
clan machines list
#> jon
```
**Finally** deployment time!
Use the following command to build and deploy the image via SSH onto your machine.
> Note: This may take a while for building and for the file transfer.
```bash
clan machines install my-machine <target_host>
```
@@ -112,6 +312,32 @@ Coming Soon:
---
A concrete command in our example will look like this
```bash
clan machines install jon root@192.168.188.50
```
> Note: the CLI will ask:
> `Install jon to root@192.168.188.50? [y/N]`
> Confirm with `y` after checking that for correctness
If you didn't generate any secrets yet. The deployment command will fail (Don't worry you can re-run it). See [secrets-management](./secrets-management.md) for how to generate your initial secrets.
#### 🎉 🚀 Your machine is all set up
---
## What's next ?
- [**Tweak Your Machine Setup**](#update-your-machines): Learn how to update an existing machine?
Coming Soon:
- **Join Your Machines in a Private Network:**: Stay tuned for steps on linking all your machines into a secure mesh network with Clan.
---
## Update Your Machines
Clan CLI enables you to remotely update your machines over SSH. This requires setting up a target address for each target machine.

33
docs/admins/quickstart.md
View File

@@ -12,9 +12,38 @@ We've put together a straightforward guide to help you out:
---
## Starting with a New Clan Project
## **Starting with a New Clan Project**
Create your own clan with these initial steps:
Create your own clan with these initial steps.
### Prerequisites
#### Linux
Clan depends on nix installed on your system. Run the following command to install nix.
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```
#### NixOS
If you run NixOS the `nix` binary is already installed.
You will also need to enable the `flakes` and `nix-commands` experimental features.
```bash
# /etc/nix/nix.conf or ~/.config/nix/nix.conf
experimental-features = nix-command flakes
```
#### Other
Clan doesn't offer dedicated support for other OS yet.
### Step 1: Add Clan CLI to Your Shell
Add the Clan CLI into your development workflow:
### Step 1: Add Clan CLI to Your Shell

5
docs/admins/secrets-management.md
View File

@@ -19,12 +19,13 @@ $ clan secrets key generate
Public key: age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7
Generated age private key at '/home/joerg/.config/sops/age/keys.txt' for your user.
Generated age private key at '/home/joerg/.config/sops/age/keys.txt' for your user. Please back it up on a secure location or you will lose access to your secrets.
Also add your age public key to the repository with 'clan secrets users add youruser age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7' (replace you
user with your user name)
Also add your age public key to the repository with 'clan secrets users add YOUR_USER age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7' (replace YOUR_USER with your actual username)
```
⚠️ **Important**: Backup the generated private key securely, or risk losing access to your secrets.
> Note: All generated secrets that the `clan CLI` places in your repository are safe to be commit into version control (i.e. with `git`).
Next, add your public key to the Clan flake repository:
```shellSession