From b1f6dd58f31efb0d70a0078ac2c85c5befd7d4ce Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Fri, 3 Oct 2025 16:50:10 +0200 Subject: [PATCH] docs: move getting-started out of guides --- docs/mkdocs.yml | 22 +++++++++---------- .../getting-started/add-machines.md | 6 ++--- .../getting-started/add-services.md | 8 +++---- .../{guides => }/getting-started/add-users.md | 10 ++++----- .../getting-started/configure-disk.md | 0 .../getting-started/continuous-integration.md | 0 .../convert-existing-NixOS-configuration.md | 4 ++-- .../creating-your-first-clan.md | 0 .../flash-installer.md | 2 +- .../install-machine.md | 10 ++++----- .../deploy-to-virtual-machine.md | 0 .../getting-started/update-machines.md | 4 ++-- docs/site/guides/inventory/inventory.md | 4 ++-- docs/site/guides/nixos-rebuild.md | 2 +- docs/site/index.md | 2 +- pkgs/clan-cli/clan_cli/cli.py | 8 +++---- pkgs/clan-cli/clan_cli/machines/cli.py | 6 ++--- 17 files changed, 43 insertions(+), 45 deletions(-) rename docs/site/{guides => }/getting-started/add-machines.md (92%) rename docs/site/{guides => }/getting-started/add-services.md (86%) rename docs/site/{guides => }/getting-started/add-users.md (87%) rename docs/site/{guides => }/getting-started/configure-disk.md (100%) rename docs/site/{guides => }/getting-started/continuous-integration.md (100%) rename docs/site/{guides => }/getting-started/convert-existing-NixOS-configuration.md (98%) rename docs/site/{guides => }/getting-started/creating-your-first-clan.md (100%) rename docs/site/{guides => }/getting-started/deploy-to-physical-machine/flash-installer.md (96%) rename docs/site/{guides => }/getting-started/deploy-to-physical-machine/install-machine.md (93%) rename docs/site/{guides => }/getting-started/deploy-to-virtual-machine.md (100%) rename docs/site/{guides => }/getting-started/update-machines.md (95%) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 3c4be64c0..b75bbf123 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -47,18 +47,18 @@ exclude_docs: | nav: - Getting Started: - Overview: index.md - - guides/getting-started/creating-your-first-clan.md - - guides/getting-started/add-machines.md - - guides/getting-started/add-users.md - - guides/getting-started/add-services.md + - getting-started/creating-your-first-clan.md + - getting-started/add-machines.md + - getting-started/add-users.md + - getting-started/add-services.md - Deploy to Physical Machine: - - guides/getting-started/deploy-to-physical-machine/flash-installer.md - - guides/getting-started/deploy-to-physical-machine/install-machine.md - - guides/getting-started/deploy-to-virtual-machine.md - - guides/getting-started/configure-disk.md - - guides/getting-started/update-machines.md - - guides/getting-started/continuous-integration.md - - guides/getting-started/convert-existing-NixOS-configuration.md + - getting-started/deploy-to-physical-machine/flash-installer.md + - getting-started/deploy-to-physical-machine/install-machine.md + - getting-started/deploy-to-virtual-machine.md + - getting-started/configure-disk.md + - getting-started/update-machines.md + - getting-started/continuous-integration.md + - getting-started/convert-existing-NixOS-configuration.md - Guides: - Inventory: - Introduction to Inventory: guides/inventory/inventory.md diff --git a/docs/site/guides/getting-started/add-machines.md b/docs/site/getting-started/add-machines.md similarity index 92% rename from docs/site/guides/getting-started/add-machines.md rename to docs/site/getting-started/add-machines.md index a7e6240e3..7f46d8a14 100644 --- a/docs/site/guides/getting-started/add-machines.md +++ b/docs/site/getting-started/add-machines.md @@ -1,10 +1,10 @@ Machines can be added using the following methods -- Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](../inventory/autoincludes.md)) +- Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](/guides/inventory/autoincludes.md)) - Imperative via cli command: `clan machines create` - Editing nix expressions in flake.nix See [`clan-core.lib.clan`](/options/?scope=Flake Options (clan.nix file)) -See the complete [list](../inventory/autoincludes.md) of auto-loaded files. +See the complete [list](/guides/inventory/autoincludes.md) of auto-loaded files. ## Create a machine @@ -18,8 +18,6 @@ See the complete [list](../inventory/autoincludes.md) of auto-loaded files. }; # Additional NixOS configuration can be added here. - # machines/jon/configuration.nix will be automatically imported. - # See: https://docs.clan.lol/guides/more-machines/#automatic-registration machines = { # jon = { config, ... }: { # environment.systemPackages = [ pkgs.asciinema ]; diff --git a/docs/site/guides/getting-started/add-services.md b/docs/site/getting-started/add-services.md similarity index 86% rename from docs/site/guides/getting-started/add-services.md rename to docs/site/getting-started/add-services.md index 5d00f5540..57433e7b5 100644 --- a/docs/site/guides/getting-started/add-services.md +++ b/docs/site/getting-started/add-services.md @@ -8,7 +8,7 @@ In Clan Services are multi-Host & role-based: - You can use tags instead of explicit machine names. -To learn more: [Guide about clanService](../inventory/clanServices.md) +To learn more: [Guide about clanService](/guides/inventory/clanServices.md) !!! Important It is recommended to add at least one networking service such as `zerotier` that allows to reach all your clan machines from your setup computer across the globe. @@ -38,8 +38,8 @@ To learn more: [Guide about clanService](../inventory/clanServices.md) } ``` -1. See [reference/clanServices](../../reference/clanServices/index.md) for all available services and how to configure them. - Or read [authoring/clanServices](../services/community.md) if you want to bring your own +1. See [reference/clanServices](/reference/clanServices/index.md) for all available services and how to configure them. + Or read [authoring/clanServices](/guides/services/community.md) if you want to bring your own 2. Replace `__YOUR_CONTROLLER_` with the *name* of your machine. @@ -71,5 +71,5 @@ Adding the following services is recommended for most users: ``` 1. The `admin` service will generate a **root-password** and **add your ssh-key** that allows for convienient administration. -2. Equivalent to directly setting `authorizedKeys` like in [configuring a machine](./add-machines.md#configuring-a-machine) +2. Equivalent to directly setting `authorizedKeys` like in [configuring a machine](/getting-started/add-machines.md#configuring-a-machine) 3. Adds `user = jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment. diff --git a/docs/site/guides/getting-started/add-users.md b/docs/site/getting-started/add-users.md similarity index 87% rename from docs/site/guides/getting-started/add-users.md rename to docs/site/getting-started/add-users.md index 824a35e24..60e9d9ed9 100644 --- a/docs/site/guides/getting-started/add-users.md +++ b/docs/site/getting-started/add-users.md @@ -3,15 +3,15 @@ The users concept of clan is not done yet. This guide outlines some solutions from our community. Defining users can be done in many different ways. We want to highlight two approaches: -- Using clan's [users](../../reference/clanServices/users.md) service. +- Using clan's [users](/reference/clanServices/users.md) service. - Using a custom approach. -## Adding Users using the [users](../../reference/clanServices/users.md) service +## Adding Users using the [users](/reference/clanServices/users.md) service To add a first *user* this guide will be leveraging two things: -- [clanServices](../../reference/clanServices/index.md): Allows to bind arbitrary logic to something we call an `ìnstance`. -- [clanServices/users](../../reference/clanServices/users.md): Implements logic for adding a single user perInstance. +- [clanServices](/reference/clanServices/index.md): Allows to bind arbitrary logic to something we call an `ìnstance`. +- [clanServices/users](/reference/clanServices/users.md): Implements logic for adding a single user perInstance. The example shows how to add a user called `jon`: @@ -49,7 +49,7 @@ The example shows how to add a user called `jon`: 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) +For more information see [clanService/users](/reference/clanServices/users.md) ## Using a custom approach diff --git a/docs/site/guides/getting-started/configure-disk.md b/docs/site/getting-started/configure-disk.md similarity index 100% rename from docs/site/guides/getting-started/configure-disk.md rename to docs/site/getting-started/configure-disk.md diff --git a/docs/site/guides/getting-started/continuous-integration.md b/docs/site/getting-started/continuous-integration.md similarity index 100% rename from docs/site/guides/getting-started/continuous-integration.md rename to docs/site/getting-started/continuous-integration.md diff --git a/docs/site/guides/getting-started/convert-existing-NixOS-configuration.md b/docs/site/getting-started/convert-existing-NixOS-configuration.md similarity index 98% rename from docs/site/guides/getting-started/convert-existing-NixOS-configuration.md rename to docs/site/getting-started/convert-existing-NixOS-configuration.md index 8f0a7cce6..55c3ca6ad 100644 --- a/docs/site/guides/getting-started/convert-existing-NixOS-configuration.md +++ b/docs/site/getting-started/convert-existing-NixOS-configuration.md @@ -2,7 +2,7 @@ This guide will help you convert your existing NixOS configurations into a Clan. !!! Warning Migrating instead of starting new can be trickier and might lead to bugs or - unexpected issues. We recommend reading the [Getting Started](/guides/getting-started/creating-your-first-clan.md) guide first. + unexpected issues. We recommend reading the [Getting Started](/getting-started/creating-your-first-clan.md) guide first. Once you have a working setup and understand the concepts transfering your NixOS configurations over is easy. @@ -169,7 +169,7 @@ Clan needs to know where it can reach your hosts. For testing purpose set } ``` -See our guide on for properly [configuring machines networking](../networking/networking.md) +See our guide on for properly [configuring machines networking](/guides/networking/networking.md) ## Next Steps diff --git a/docs/site/guides/getting-started/creating-your-first-clan.md b/docs/site/getting-started/creating-your-first-clan.md similarity index 100% rename from docs/site/guides/getting-started/creating-your-first-clan.md rename to docs/site/getting-started/creating-your-first-clan.md diff --git a/docs/site/guides/getting-started/deploy-to-physical-machine/flash-installer.md b/docs/site/getting-started/deploy-to-physical-machine/flash-installer.md similarity index 96% rename from docs/site/guides/getting-started/deploy-to-physical-machine/flash-installer.md rename to docs/site/getting-started/deploy-to-physical-machine/flash-installer.md index 41b928f56..6ab7cae15 100644 --- a/docs/site/guides/getting-started/deploy-to-physical-machine/flash-installer.md +++ b/docs/site/getting-started/deploy-to-physical-machine/flash-installer.md @@ -1,7 +1,7 @@ To install Clan on physical machines, you need to use our custom installer image. This is necessary for proper installation and operation. !!! 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](/guides/getting-started/deploy-to-virtual-machine.md) step. In this scenario, we automatically use [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to replace the kernel during runtime. + If you're deploying to a virtual machine (VM), you can skip this section and go directly to the [Deploy Virtual Machine](/getting-started/deploy-to-virtual-machine.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. diff --git a/docs/site/guides/getting-started/deploy-to-physical-machine/install-machine.md b/docs/site/getting-started/deploy-to-physical-machine/install-machine.md similarity index 93% rename from docs/site/guides/getting-started/deploy-to-physical-machine/install-machine.md rename to docs/site/getting-started/deploy-to-physical-machine/install-machine.md index c1200f405..6395bbd81 100644 --- a/docs/site/guides/getting-started/deploy-to-physical-machine/install-machine.md +++ b/docs/site/getting-started/deploy-to-physical-machine/install-machine.md @@ -4,13 +4,13 @@ Now that you have created a machine, added some services, and set up secrets, th ### 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](/guides/getting-started/add-machines.md) +- [x] **Machine configuration**: See our basic [adding and configuring machine guide](/getting-started/add-machines.md) - [x] **Initialized secrets**: See [secrets](/guides/secrets.md) for how to initialize your secrets. -- [x] **USB Flash Drive**: See [Clan Installer](/guides/getting-started/flash-installer.md) +- [x] **USB Flash Drive**: See [Clan Installer](/getting-started/flash-installer.md) ### Image Installer -This method makes use of the [image installers](/guides/getting-started/flash-installer.md). +This method makes use of the [image installers](/getting-started/flash-installer.md). 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. @@ -66,7 +66,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](/guides/getting-started/flash-installer.md). +3. See how to connect the installer medium to wlan [here](/getting-started/flash-installer.md). !!!tip For easy sharing of deployment information via QR code, we highly recommend using [KDE Connect](https://apps.kde.org/de/kdeconnect/). @@ -111,4 +111,4 @@ The following command will generate a hardware report with [nixos-facter](https: If you are using our template `[MACHINE]` would be `jon` -[Next Step (Choose Disk Format)](/guides/getting-started/configure-disk.md){ .md-button .md-button--primary } \ No newline at end of file +[Next Step (Choose Disk Format)](/getting-started/configure-disk.md){ .md-button .md-button--primary } \ No newline at end of file diff --git a/docs/site/guides/getting-started/deploy-to-virtual-machine.md b/docs/site/getting-started/deploy-to-virtual-machine.md similarity index 100% rename from docs/site/guides/getting-started/deploy-to-virtual-machine.md rename to docs/site/getting-started/deploy-to-virtual-machine.md diff --git a/docs/site/guides/getting-started/update-machines.md b/docs/site/getting-started/update-machines.md similarity index 95% rename from docs/site/guides/getting-started/update-machines.md rename to docs/site/getting-started/update-machines.md index 05179c12a..82cfffda3 100644 --- a/docs/site/guides/getting-started/update-machines.md +++ b/docs/site/getting-started/update-machines.md @@ -31,7 +31,7 @@ Ensure that the root login is secured and only used when necessary. ## Multiple Target Hosts -You can now experiment with a new interface that allows you to define multiple `targetHost` addresses for different VPNs. Learn more and try it out in our [networking guide](../networking/networking.md). +You can now experiment with a new interface that allows you to define multiple `targetHost` addresses for different VPNs. Learn more and try it out in our [networking guide](/guides/networking/networking.md). ## Updating Machine Configurations @@ -78,7 +78,7 @@ clan { `buildHost` / `targetHost`, and other network settings can be temporarily overridden for a single command: -For the full list of flags refer to the [Clan CLI](../../reference/cli/index.md) +For the full list of flags refer to the [Clan CLI](/reference/cli/index.md) ```bash # Build on a remote host diff --git a/docs/site/guides/inventory/inventory.md b/docs/site/guides/inventory/inventory.md index 4659849f2..748f51f93 100644 --- a/docs/site/guides/inventory/inventory.md +++ b/docs/site/guides/inventory/inventory.md @@ -17,13 +17,13 @@ The following tutorial will walk through setting up a Backup service where the t ## Prerequisites -- [x] [Add some machines](../getting-started/add-machines.md) to your Clan. +- [x] [Add some machines](/getting-started/add-machines.md) to your Clan. ## Services The inventory defines `instances` of clan services. Membership of `machines` is defined via `roles` exclusively. -See each [modules documentation](../../reference/clanServices/index.md) for its available roles. +See each [modules documentation](/reference/clanServices/index.md) for its available roles. ### Adding services to machines diff --git a/docs/site/guides/nixos-rebuild.md b/docs/site/guides/nixos-rebuild.md index 8d176bca2..a34da1edb 100644 --- a/docs/site/guides/nixos-rebuild.md +++ b/docs/site/guides/nixos-rebuild.md @@ -64,5 +64,5 @@ nixos-rebuild switch --flake .#my-machine --target-host root@target-ip --build-h ## Related Documentation -- [Update Your Machines](/guides/getting-started/update-machine.md) - Using clan's update command +- [Update Your Machines](/getting-started/update-machine.md) - Using clan's update command - [Variables (Vars)](/guides/vars/vars-overview.md) - Understanding the vars system diff --git a/docs/site/index.md b/docs/site/index.md index feefe6bf2..799d80c60 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -85,7 +85,7 @@ hide: --- -[Get started](/guides/getting-started/creating-your-first-clan){ .md-button .md-button--primary } +[Get started](/getting-started/creating-your-first-clan.md){ .md-button .md-button--primary } [View on Gitea](https://git.clan.lol/clan/clan-core){ .md-button } ## Guides diff --git a/pkgs/clan-cli/clan_cli/cli.py b/pkgs/clan-cli/clan_cli/cli.py index 8b728c887..b13970500 100644 --- a/pkgs/clan-cli/clan_cli/cli.py +++ b/pkgs/clan-cli/clan_cli/cli.py @@ -179,7 +179,7 @@ Examples: Will create a new clan flake in the specified directory and create it if it doesn't exist yet. The flake will be created from a default template. -For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/creating-your-first-clan")} +For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/getting-started/creating-your-first-clan")} """ ), formatter_class=argparse.RawTextHelpFormatter, @@ -253,7 +253,7 @@ Examples: $ clan flash write mymachine --disk main /dev/sd --ssh-pubkey ~/.ssh/id_rsa.pub Will flash the machine 'mymachine' to the disk '/dev/sd' 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/deploy-to-physical-machine/flash-installer")} +For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/getting-started/deploy-to-physical-machine/flash-installer")} """ ), formatter_class=argparse.RawTextHelpFormatter, @@ -280,7 +280,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-to-physical-machine/install-machine")} +For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/getting-started/deploy-to-physical-machine/install-machine")} """ ), formatter_class=argparse.RawTextHelpFormatter, @@ -411,7 +411,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/update-machines")} +For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/getting-started/update-machines")} """ ), formatter_class=argparse.RawTextHelpFormatter, diff --git a/pkgs/clan-cli/clan_cli/machines/cli.py b/pkgs/clan-cli/clan_cli/machines/cli.py index dfd6be391..e424c1450 100644 --- a/pkgs/clan-cli/clan_cli/machines/cli.py +++ b/pkgs/clan-cli/clan_cli/machines/cli.py @@ -48,7 +48,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/update-machines +For more detailed information, visit: https://docs.clan.lol/getting-started/update-machines """ ), formatter_class=argparse.RawTextHelpFormatter, @@ -156,8 +156,8 @@ Examples: Further references: -- https://docs.clan.lol/guides/getting-started/deploy-to-physical-machine/ -- https://docs.clan.lol/guides/getting-started/deploy-to-virtual-machine/ +- https://docs.clan.lol/getting-started/deploy-to-physical-machine/ +- https://docs.clan.lol/getting-started/deploy-to-virtual-machine/ """ ), formatter_class=argparse.RawTextHelpFormatter,