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

docs: review fixups

Browse Source 
docs: review fixups

docs: review fixups

docs: fixup links in cli

docs: fixup links in cli
This commit is contained in:
Qubasa
2025-07-31 17:04:15 +07:00
parent d2529704d5
commit 0b05b0b1ec
12 changed files with 54 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/site/guides/getting-started/add-user.md
View File

@@ -49,7 +49,7 @@ The example shows how to add a user called `jon`:
2. Add this user to `all` machines
3. Define the `name` of the user to be `jon`
The `users` service creates a `/home/jon` directory, allows `jon` to sign in and will take care of the users password as part of [deployment](./deploy.md).
The `users` service creates a `/home/jon` directory, allows `jon` to sign in and will take care of the user's password.
For more information see [clanService/users](../../reference/clanServices/users.md)

36
docs/site/guides/getting-started/choose-disk.md
View File

@@ -2,6 +2,34 @@
By default clan uses [disko](https://github.com/nix-community/disko) which allows for declarative disk partitioning.
To see what disk templates are available run:
```{.shellSession hl_lines="10" .no-copy}
$ clan templates list
Available 'clan' template
├── <builtin>
│ ├── default: Initialize a new clan flake
│ ├── flake-parts: Flake-parts
│ └── minimal: for clans managed via (G)UI
Available 'disko' templates
├── <builtin>
│ └── single-disk: A simple ext4 disk with a single partition
Available 'machine' templates
├── <builtin>
│ ├── demo-template: Demo machine for the CLAN project
│ ├── flash-installer: Initialize a new flash-installer machine
│ ├── new-machine: Initialize a new machine
│ └── test-morph-template: Morph a machine
```
For this guide we will select the `single-disk` template, that uses `A simple ext4 disk with a single partition`.
!!! 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).
You can also [contribute a disk template to clan core](https://docs.clan.lol/guides/disko-templates/community/)
To setup a disk schema for a machine run
```bash
@@ -30,16 +58,10 @@ Applied disk template 'single-disk' to machine 'jon'
A disko.nix file should be created in `machines/jon`
You can have a look and customize it if needed.
!!! 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).
!!! Danger
Don't change the `disko.nix` after the machine is installed for the first time.
Don't change the `disko.nix` after the machine is installed for the first time, unless you really know what you are doing.
Changing disko configuration requires wiping and reinstalling the machine.
Unless you really know what you are doing.
## Deploy the machine
**Finally deployment time!**

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

@@ -2,8 +2,8 @@
To install Clan on physical machines, you need to use our custom installer image. This is necessary for proper installation and operation.
!!! 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 [Deploy Virtual Machine](./hardware-report-virtual.md) step. In this scenario, we automatically use [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to replace the kernel during runtime.
!!! note "Deploying to a Virtual Machine?"
If you're deploying to a virtual machine (VM), you can skip this section and go directly to the [Deploy Virtual Machine](./hardware-report-virtual.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.

13
docs/site/guides/getting-started/hardware-report-physical.md
View File

@@ -1,20 +1,21 @@
# Installing a Physical Machine
Now that you have created a machines, added some services and setup secrets. This guide will walk through how to deploy it.
Now that you have created a machine, added some services, and set up secrets, this guide will walk you through how to deploy it.
### Step 0. Prerequisites
- [x] RAM > 2GB
- [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 [adding and configuring machine guide](./add-machines.md)
- [x] **Initialized secrets**: See [secrets](secrets.md) for how to initialize your secrets.
- [x] **Initialized secrets**: See [secrets](../secrets.md) for how to initialize your secrets.
- [x] **USB Flash Drive**: See [Clan Installer](./create-installer.md)
### Image Installer
This method makes use of the [image installers](./create-installer.md).
The installer will randomly generate a password and local addresses on boot, then run ssh with these preconfigured.
The installer shows it's deployment relevant information in two formats, a text form, as well as a QR code.
The installer will randomly generate a password and local addresses on boot, then run a SSH server with these preconfigured.
The installer shows its deployment relevant information in two formats, a text form, as well as a QR code.
This is an example of the booted installer.
@@ -67,9 +68,7 @@ This is an example of the booted installer.
```
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).
4. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
text__, images, ... basically anything that can be written in Markdown.
3. See how to connect the installer medium to wlan [here](./create-installer.md).
!!!tip
For easy sharing of deployment information via QR code, we highly recommend using [KDE Connect](https://apps.kde.org/de/kdeconnect/).

3
docs/site/guides/getting-started/hardware-report-virtual.md
View File

@@ -1,6 +1,7 @@
# Generate a VM Hardware Report
Now that you have created a machines, added some services and setup secrets. This guide will walk through how to deploy it.
Now that you have created a machine, added some services, and set up secrets, this guide will walk you through how to deploy it.
## Prerequisites
- [x] RAM > 2GB

2
docs/site/guides/getting-started/update.md
View File

@@ -5,7 +5,7 @@ Clan CLI enables you to remotely update your machines over SSH. This requires se
### Setting `targetHost`
In your nix files set the targetHost (reachable ip) that your new machine now has. This removes the need to add `--targetHost` to every command.
In your Nix files, set the `targetHost` to the reachable IP address of your new machine. This eliminates the need to specify `--target-host` with every command.
```{.nix title="clan.nix" hl_lines="9"}

6
pkgs/clan-cli/clan_cli/cli.py
View File

@@ -244,7 +244,7 @@ Examples:
$ clan flash write mymachine --disk main /dev/sd<X> --ssh-pubkey ~/.ssh/id_rsa.pub
Will flash the machine 'mymachine' to the disk '/dev/sd<X>' with the ssh public key '~/.ssh/id_rsa.pub'.
For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/installer")}
For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/create-installer")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -271,7 +271,7 @@ Examples:
the json string. [JSON] can either be a json formatted string itself, or point
towards a file containing the deployment information
For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/hardware-report-physical")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -402,7 +402,7 @@ Examples:
If the `--target-host` flag is omitted will try to find host information by
checking the deployment configuration inside the specified machine.
For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/update")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,

6
pkgs/clan-cli/clan_cli/machines/cli.py
View File

@@ -47,7 +47,7 @@ Examples:
$ clan machines update machine1 machine2 --tags production
Will update only machine1 and machine2 if they both have the "production" tag.
For more detailed information, visit: https://docs.clan.lol/guides/getting-started/deploy
For more detailed information, visit: https://docs.clan.lol/guides/getting-started/update
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -133,8 +133,8 @@ Examples:
Will install the specified machine [MACHINE] to the host exposed by
the deployment information of the [JSON] deployment string.
For information on how to set up the installer see: https://docs.clan.lol/guides/getting-started/installer/
For more detailed information, visit: https://docs.clan.lol/guides/getting-started/deploy
For information on how to set up the installer see: https://docs.clan.lol/guides/getting-started/create-installer/
For more detailed information, visit: https://docs.clan.lol/guides/getting-started/hardware-report-physical
"""
),
formatter_class=argparse.RawTextHelpFormatter,

4
pkgs/clan-cli/clan_lib/machines/install.py
View File

@@ -13,7 +13,7 @@ from clan_lib.api import API
from clan_lib.cmd import Log, RunOpts, run
from clan_lib.machines.machines import Machine
from clan_lib.nix import nix_shell
from clan_lib.ssh.create import create_nixos_anywhere_ssh_key
from clan_lib.ssh.create import create_secret_key_nixos_anywhere
from clan_lib.ssh.remote import Remote
log = logging.getLogger(__name__)
@@ -122,7 +122,7 @@ def run_machine_install(opts: InstallOptions, target_host: Remote) -> None:
# The kexec phase requires an authorized key, and if not specified,
# nixos-anywhere defaults to a key in a temporary directory.
if opts.anywhere_priv_key is None:
key_pair = create_nixos_anywhere_ssh_key()
key_pair = create_secret_key_nixos_anywhere()
opts.anywhere_priv_key = key_pair.private
cmd += ["-i", str(opts.anywhere_priv_key)]

2
pkgs/clan-cli/clan_lib/machines/machines.py
View File

@@ -133,7 +133,7 @@ class Machine:
msg = f"'targetHost' is not set for machine '{self.name}'"
raise ClanError(
msg,
description="See https://docs.clan.lol/guides/getting-started/deploy/#setting-the-target-host for more information.",
description="See https://docs.clan.lol/guides/getting-started/update/#setting-the-target-host for more information.",
)
data = remote.data
return data

4
pkgs/clan-cli/clan_lib/ssh/create.py
View File

@@ -2,7 +2,6 @@ import logging
from dataclasses import dataclass
from pathlib import Path
from clan_lib.api import API
from clan_lib.cmd import Log, RunOpts, run
from clan_lib.dirs import user_nixos_anywhere_dir
@@ -15,8 +14,7 @@ class SSHKeyPair:
public: Path
@API.register
def create_nixos_anywhere_ssh_key() -> SSHKeyPair:
def create_secret_key_nixos_anywhere() -> SSHKeyPair:
"""
Create a new SSH key pair for NixOS Anywhere.
The keys are stored in ~/.config/clan/nixos-anywhere/keys/id_ed25519 and id_ed25519.pub.

6
pkgs/clan-cli/clan_lib/ssh/create_test.py
View File

@@ -1,10 +1,10 @@
from pathlib import Path
from clan_lib.ssh.create import create_nixos_anywhere_ssh_key
from clan_lib.ssh.create import create_secret_key_nixos_anywhere
def test_clan_generate_sshkeys(temporary_home: Path) -> None:
keypair = create_nixos_anywhere_ssh_key()
keypair = create_secret_key_nixos_anywhere()
assert keypair.private.exists()
assert keypair.public.exists()
@@ -22,7 +22,7 @@ def test_clan_generate_sshkeys(temporary_home: Path) -> None:
assert "PRIVATE KEY" in keypair.private.read_text()
assert "ssh-ed25519" in keypair.public.read_text()
new_keypair = create_nixos_anywhere_ssh_key()
new_keypair = create_secret_key_nixos_anywhere()
assert new_keypair.private == keypair.private
assert new_keypair.public == keypair.public