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

docs: remove step numbers

Browse Source 
Numerating steps is not informative and considered bad style
People tend to follow documentation non-linearly
leaving of at one point, starting over from the middle
Documentation should be written in a way that allow for that
This commit is contained in:
Johannes Kirschbauer
2025-07-02 15:53:24 +02:00
parent d7dcb55001
commit 6c7beb7aaa
8 changed files with 55 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/site/guides/getting-started/deploy.md
View File

@@ -27,7 +27,7 @@ Now that you have created a new machine, we will walk through how to install it.
!!! Warning "NixOS can cause strange issues when booting in certain cloud environments."
If on Linode: Make sure that the system uses Direct Disk boot kernel (found in the configuration pannel)
### Step 1. Setting `targetHost`
## Setting `targetHost`
=== "flake.nix (flake-parts)"
@@ -98,7 +98,7 @@ Now that you have created a new machine, we will walk through how to install it.
The use of `root@` in the target address implies SSH access as the `root` user.
Ensure that the root login is secured and only used when necessary.
### Step 2. Identify the Target Disk
## Identify the Target Disk
On the setup computer, SSH into the target:
@@ -129,7 +129,7 @@ In this example we would copy `nvme-eui.e8238fa6bf530001001b448b4aec2929`
!!! tip
For advanced partitioning, see [Disko templates](https://github.com/nix-community/disko-templates) or [Disko examples](https://github.com/nix-community/disko/tree/master/example).
### Step 3. Fill in hardware specific machine configuration
## Fill in hardware specific machine configuration
Edit the following fields inside the `./machines/<machine_name>/configuration.nix`
@@ -164,7 +164,7 @@ Edit the following fields inside the `./machines/<machine_name>/configuration.ni
!!! Info "Replace `__CHANGE_ME__` with the appropriate `ID-LINK` identifier, such as `nvme-eui.e8238fa6bf530001001b448b4aec2929`"
!!! Info "Replace `__YOUR_SSH_KEY__` with your personal key, like `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILoMI0NC5eT9pHlQExrvR5ASV3iW9+BXwhfchq0smXUJ jon@jon-desktop`"
### Step 4. Deploy the machine
## Deploy the machine
**Finally deployment time!** Use the following command to build and deploy the image via SSH onto your machine.
@@ -227,7 +227,7 @@ Edit the following fields inside the `./machines/<machine_name>/configuration.ni
```
2. The root password for the installer medium.
This password is autogenerated and meant to be easily typeable.
3. See how to connect the installer medium to wlan [here](./installer.md#optional-connect-to-wifi-manually).
3. See [how to connect to wlan](./installer.md#optional-connect-to-wifi-manually).
!!! tip
Use [KDE Connect](https://apps.kde.org/de/kdeconnect/) for easyily sharing QR codes from phone to desktop
@@ -236,21 +236,21 @@ Edit the following fields inside the `./machines/<machine_name>/configuration.ni
Just run the command **Option B: Cloud VM** below
#### Deployment Commands
### Deployment Commands
##### Using password auth
#### Using password auth
```bash
clan machines install [MACHINE] --target-host <IP> --update-hardware-config nixos-facter
```
##### Using QR JSON
#### Using QR JSON
```bash
clan machines install [MACHINE] --json "[JSON]" --update-hardware-config nixos-facter
```
##### Using QR image file
#### Using QR image file
```bash
clan machines install [MACHINE] --png [PATH] --update-hardware-config nixos-facter

27
docs/site/guides/getting-started/index.md
View File

@@ -4,8 +4,7 @@ Ready to create your own Clan and manage a fleet of machines? Follow these simpl
By the end of this guide, you'll have a fresh NixOS configuration ready to push to one or more machines. You'll create a new Git repository and a flake, and all you need is at least one machine to push to. This is the easiest way to begin, and we recommend you to copy your existing configuration into this new setup!
### Prerequisites
## Prerequisites
=== "**Linux**"
@@ -37,22 +36,23 @@ By the end of this guide, you'll have a fresh NixOS configuration ready to push
If you have previously installed Nix, make sure `experimental-features = nix-command flakes` is present in `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`. If this is not the case, please add it to `~/.config/nix/nix.conf`.
### Step 1: Add Clan CLI to Your Shell
## Add Clan CLI to Your Shell
Add the Clan CLI into your development workflow:
Add the Clan CLI into your environment:
```bash
nix shell git+https://git.clan.lol/clan/clan-core#clan-cli --refresh
```
You can find reference documentation for the `clan` CLI program [here](../../reference/cli/index.md).
Alternatively you can check out the help pages directly:
```terminalSession
clan --help
```
### Step 2: Initialize Your Project
Should print the avilable commands.
Also checkout the [cli-reference documentation](../../reference/cli/index.md).
## Initialize Your Project
If you want to migrate an existing project, follow this [guide](../migrations/migration-guide.md).
@@ -62,19 +62,18 @@ Set the foundation of your Clan project by initializing it by running:
clan flakes create my-clan
```
This command creates the `flake.nix` and `.clan-flake` files for your project.
It will also generate files from a default template, to help show general clan usage patterns.
This command creates a `flake.nix` and some other files for your project.
### Step 3: Verify the Project Structure
## Verify the Project Structure
Ensure that all project files exist by running:
Take a lookg at all project files:
```bash
cd my-clan
tree
```
This should yield the following:
Depending on the current template you should see something like this:
``` { .console .no-copy }
.
@@ -109,7 +108,6 @@ This should yield the following:
To automatically add the `clan` CLI tool to your environment without having to
run `nix develop` every time, we recommend setting up [direnv](https://direnv.net/).
```bash
clan machines list
```
@@ -122,4 +120,3 @@ sara
!!! success
You just successfully bootstrapped your first Clan.

13
docs/site/guides/getting-started/installer.md
View File

@@ -11,13 +11,12 @@ To install Clan on physical machines, you need to use our custom installer image
??? 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.
### Step 0. Prerequisites
## Prerequisites
- [x] A free USB Drive with at least 1.5GB (All data on it will be lost)
- [x] Linux/NixOS Machine with Internet
### Step 1. Identify the USB Flash Drive
## Identify the USB Flash Drive
1. Insert your USB flash drive into your computer.
@@ -45,7 +44,7 @@ To install Clan on physical machines, you need to use our custom installer image
sudo umount /dev/sdb1
```
### Step 2. Installer
## Installer
=== "**Linux OS**"
**Create a Custom Installer**
@@ -118,7 +117,7 @@ sudo umount /dev/sdb1
!!! Note
If you don't have `wget` installed, you can use `curl --progress-bar -OL <url>` instead.
### Step 2.5 Flash the Installer to the USB Drive
## Flash the Installer to the USB Drive
!!! Danger "Specifying the wrong device can lead to unrecoverable data loss."
@@ -151,11 +150,10 @@ sudo umount /dev/sdb1
If you need to configure Wi-Fi first, refer to the next section.
If Multicast-DNS (Avahi) is enabled on your own machine, you can also access the installer using the `nixos-installer.local` address.
## Boot From USB Stick
### Step 3: Boot From USB Stick
- To use, boot from the Clan USB drive with **secure boot turned off**. For step by step instructions go to [Disabling Secure Boot](../../guides/secure-boot.md)
## (Optional) Connect to Wifi Manually
If you don't have access via LAN the Installer offers support for connecting via Wifi.
@@ -203,4 +201,3 @@ Press ++ctrl+d++ to exit `IWD`.
Press ++ctrl+d++ **again** to update the displayed QR code and connection information.
You're all set up