diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 13aa6a7c9..3c4be64c0 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -47,18 +47,18 @@ exclude_docs: | nav: - Getting Started: - Overview: index.md - - Creating Your First Clan: guides/getting-started/index.md - - Add Machines: guides/getting-started/add-machines.md - - Add User: guides/getting-started/add-user.md - - Add Services: guides/getting-started/add-services.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 - Deploy to Physical Machine: - - Create USB Installer: guides/getting-started/create-installer.md - - Deploy Physical Machine: guides/getting-started/hardware-report-physical.md - - Deploy to Virtual Machine: guides/getting-started/hardware-report-virtual.md - - Configure Disk Config: guides/getting-started/choose-disk.md - - Update Machine: guides/getting-started/update.md - - Continuous Integration: guides/getting-started/flake-check.md - - Convert Existing NixOS Config: guides/getting-started/convert-flake.md + - 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 - Guides: - Inventory: - Introduction to Inventory: guides/inventory/inventory.md diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py index 486929559..e3da219a1 100644 --- a/docs/nix/render_options/__init__.py +++ b/docs/nix/render_options/__init__.py @@ -497,8 +497,8 @@ def produce_clan_options_docs() -> None: output = """# Clan Options This provides an overview of the available options -Those can be set via [`clan-core.lib.clan`](./clan.md#inventory) function, -or via the [`clan`](./clan.md) attribute of flake-parts. +Those can be set via [`clan-core.lib.clan`](/reference/options/clan.md#inventory) function, +or via the [`clan`](/reference/options/clan.md) attribute of flake-parts. """ # Inventory options are already included under the clan attribute diff --git a/docs/site/guides/disk-encryption.md b/docs/site/guides/disk-encryption.md index 7fd06e3ea..f8e36a085 100644 --- a/docs/site/guides/disk-encryption.md +++ b/docs/site/guides/disk-encryption.md @@ -5,7 +5,7 @@ This guide provides an example setup for a single-disk ZFS system with native en This configuration only applies to `systemd-boot` enabled systems and **requires** UEFI booting. !!! Info "Secure Boot" - This guide is compatible with systems that have [secure boot disabled](./secure-boot.md). If you encounter boot issues, check if secure boot needs to be disabled in your UEFI settings. + This guide is compatible with systems that have [secure boot disabled](/guides/secure-boot.md). If you encounter boot issues, check if secure boot needs to be disabled in your UEFI settings. Replace the highlighted lines with your own disk-id. You can find our your disk-id by executing: diff --git a/docs/site/guides/getting-started/add-machines.md b/docs/site/guides/getting-started/add-machines.md index a6285cb98..a7e6240e3 100644 --- a/docs/site/guides/getting-started/add-machines.md +++ b/docs/site/guides/getting-started/add-machines.md @@ -1,5 +1,3 @@ -# How to add machines - Machines can be added using the following methods - Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](../inventory/autoincludes.md)) diff --git a/docs/site/guides/getting-started/add-services.md b/docs/site/guides/getting-started/add-services.md index 9d8dcb42f..5d00f5540 100644 --- a/docs/site/guides/getting-started/add-services.md +++ b/docs/site/guides/getting-started/add-services.md @@ -1,5 +1,3 @@ -# How to add services - A service in clan is a self-contained, reusable unit of system configuration that provides a specific piece of functionality across one or more machines. Think of it as a recipe for running a tool — like automatic backups, VPN networking, monitoring, etc. diff --git a/docs/site/guides/getting-started/add-user.md b/docs/site/guides/getting-started/add-users.md similarity index 99% rename from docs/site/guides/getting-started/add-user.md rename to docs/site/guides/getting-started/add-users.md index 46d6a50ec..824a35e24 100644 --- a/docs/site/guides/getting-started/add-user.md +++ b/docs/site/guides/getting-started/add-users.md @@ -1,5 +1,3 @@ -# How to add users - !!! Note "Under construction" The users concept of clan is not done yet. This guide outlines some solutions from our community. diff --git a/docs/site/guides/getting-started/choose-disk.md b/docs/site/guides/getting-started/configure-disk.md similarity index 96% rename from docs/site/guides/getting-started/choose-disk.md rename to docs/site/guides/getting-started/configure-disk.md index 2533a426f..bfaa9f8c2 100644 --- a/docs/site/guides/getting-started/choose-disk.md +++ b/docs/site/guides/getting-started/configure-disk.md @@ -1,5 +1,3 @@ -# Configure Disk Config - 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: @@ -64,9 +62,9 @@ You can have a look and customize it if needed. ## Deploy the machine -**Finally deployment time!** +**Finally deployment time!** -This command is destructive and will format your disk and install NixOS on it! It is equivalent to appending `--phases kexec,disko,install,reboot`. +This command is destructive and will format your disk and install NixOS on it! It is equivalent to appending `--phases kexec,disko,install,reboot`. ```bash diff --git a/docs/site/guides/getting-started/flake-check.md b/docs/site/guides/getting-started/continuous-integration.md similarity index 100% rename from docs/site/guides/getting-started/flake-check.md rename to docs/site/guides/getting-started/continuous-integration.md diff --git a/docs/site/guides/getting-started/convert-flake.md b/docs/site/guides/getting-started/convert-existing-NixOS-configuration.md similarity index 98% rename from docs/site/guides/getting-started/convert-flake.md rename to docs/site/guides/getting-started/convert-existing-NixOS-configuration.md index ba269bbde..8f0a7cce6 100644 --- a/docs/site/guides/getting-started/convert-flake.md +++ b/docs/site/guides/getting-started/convert-existing-NixOS-configuration.md @@ -1,10 +1,8 @@ -# Convert existing NixOS configurations - 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](./index.md) guide first. + unexpected issues. We recommend reading the [Getting Started](/guides/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. diff --git a/docs/site/guides/getting-started/index.md b/docs/site/guides/getting-started/creating-your-first-clan.md similarity index 94% rename from docs/site/guides/getting-started/index.md rename to docs/site/guides/getting-started/creating-your-first-clan.md index 42830bf41..e06760f94 100644 --- a/docs/site/guides/getting-started/index.md +++ b/docs/site/guides/getting-started/creating-your-first-clan.md @@ -1,6 +1,4 @@ -# :material-clock-fast: Getting Started - -Ready to manage your fleet of machines? +Ready to manage your fleet of machines? We will create a declarative infrastructure using **clan**, **git**, and **nix flakes**. @@ -43,7 +41,7 @@ Make sure you have the following: ## Create a New Clan 1. Navigate to your desired directory: - + ```shellSession cd ``` @@ -76,7 +74,7 @@ my-clan/ ``` !!! note "Templates" - This is the structure for the `default` template. + This is the structure for the `default` template. Use `clan templates list` and `clan templates --help` for available templates & more. Keep in mind that the exact files may change as templates evolve. @@ -121,7 +119,7 @@ Name: __CHANGE_ME__ Description: None ``` -This confirms your setup is working correctly. +This confirms your setup is working correctly. You can now change the default name by editing the `meta.name` field in your `clan.nix` file. diff --git a/docs/site/guides/getting-started/create-installer.md b/docs/site/guides/getting-started/deploy-to-physical-machine/flash-installer.md similarity index 95% rename from docs/site/guides/getting-started/create-installer.md rename to docs/site/guides/getting-started/deploy-to-physical-machine/flash-installer.md index 1f094eb98..41b928f56 100644 --- a/docs/site/guides/getting-started/create-installer.md +++ b/docs/site/guides/getting-started/deploy-to-physical-machine/flash-installer.md @@ -1,9 +1,7 @@ -# USB Installer Image for Physical Machines - 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](./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. + 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. ??? 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. @@ -152,7 +150,7 @@ sudo umount /dev/sdb1 ## 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](../secure-boot.md) +- To use, boot from the Clan USB drive with **secure boot turned off**. For step by step instructions go to [Disabling Secure Boot](/guides/) ## (Optional) Connect to Wifi Manually diff --git a/docs/site/guides/getting-started/hardware-report-physical.md b/docs/site/guides/getting-started/deploy-to-physical-machine/install-machine.md similarity index 92% rename from docs/site/guides/getting-started/hardware-report-physical.md rename to docs/site/guides/getting-started/deploy-to-physical-machine/install-machine.md index a60a74851..c1200f405 100644 --- a/docs/site/guides/getting-started/hardware-report-physical.md +++ b/docs/site/guides/getting-started/deploy-to-physical-machine/install-machine.md @@ -1,18 +1,16 @@ -# Installing a Physical Machine - 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 - [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] **USB Flash Drive**: See [Clan Installer](./create-installer.md) +- [x] **Machine configuration**: See our basic [adding and configuring machine guide](/guides/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) ### Image Installer -This method makes use of the [image installers](./create-installer.md). +This method makes use of the [image installers](/guides/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. @@ -68,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](./create-installer.md). +3. See how to connect the installer medium to wlan [here](/guides/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/). @@ -113,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)](./choose-disk.md){ .md-button .md-button--primary } \ No newline at end of file +[Next Step (Choose Disk Format)](/guides/getting-started/configure-disk.md){ .md-button .md-button--primary } \ No newline at end of file diff --git a/docs/site/guides/getting-started/hardware-report-virtual.md b/docs/site/guides/getting-started/deploy-to-virtual-machine.md similarity index 90% rename from docs/site/guides/getting-started/hardware-report-virtual.md rename to docs/site/guides/getting-started/deploy-to-virtual-machine.md index 957528d89..bbd2778da 100644 --- a/docs/site/guides/getting-started/hardware-report-virtual.md +++ b/docs/site/guides/getting-started/deploy-to-virtual-machine.md @@ -1,7 +1,3 @@ -# Generate a VM Hardware Report - -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 diff --git a/docs/site/guides/getting-started/update.md b/docs/site/guides/getting-started/update-machines.md similarity index 99% rename from docs/site/guides/getting-started/update.md rename to docs/site/guides/getting-started/update-machines.md index a88ef7dcf..05179c12a 100644 --- a/docs/site/guides/getting-started/update.md +++ b/docs/site/guides/getting-started/update-machines.md @@ -1,4 +1,3 @@ - # Update Machines The Clan command line interface enables you to update machines remotely over SSH. diff --git a/docs/site/guides/nixos-rebuild.md b/docs/site/guides/nixos-rebuild.md index 6a92d9446..8d176bca2 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](getting-started/update.md) - Using clan's update command -- [Variables (Vars)](vars/vars-overview.md) - Understanding the vars system +- [Update Your Machines](/guides/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 a48b18b60..feefe6bf2 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -85,7 +85,7 @@ hide: --- -[Get started](./guides/getting-started/index.md){ .md-button .md-button--primary } +[Get started](/guides/getting-started/creating-your-first-clan){ .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 2fa8be2c5..8b728c887 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/index.html")} +For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/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/create-installer")} +For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/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/hardware-report-physical")} +For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/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")} +For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/update-machines")} """ ), formatter_class=argparse.RawTextHelpFormatter, diff --git a/pkgs/clan-cli/clan_cli/hyperlink.py b/pkgs/clan-cli/clan_cli/hyperlink.py index 0370f8814..f74350c54 100644 --- a/pkgs/clan-cli/clan_cli/hyperlink.py +++ b/pkgs/clan-cli/clan_cli/hyperlink.py @@ -32,7 +32,7 @@ def help_hyperlink(description: str, url: str) -> str: def docs_hyperlink(description: str, url: str) -> str: """Returns a markdown hyperlink""" - url = url.replace("https://docs.clan.lol", "../..") + url = url.replace("https://docs.clan.lol", "/") url = url.replace("index.html", "index") url += ".md" return f"[{description}]({url})" diff --git a/pkgs/clan-cli/clan_cli/machines/cli.py b/pkgs/clan-cli/clan_cli/machines/cli.py index bb22df162..dfd6be391 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 +For more detailed information, visit: https://docs.clan.lol/guides/getting-started/update-machines """ ), formatter_class=argparse.RawTextHelpFormatter, @@ -108,9 +108,6 @@ Examples: $ clan machines init-hardware-config [MACHINE] --target-host root@ Will generate the facter.json hardware report for `[TARGET_HOST]` and place the result in facter.json for the given machine `[MACHINE]`. - -For more detailed information, visit: https://docs.clan.lol/guides/getting-started/configure/#machine-configuration - """ ), ) @@ -129,9 +126,6 @@ For more detailed information, visit: https://docs.clan.lol/guides/getting-start $ clan machines update-hardware-config [MACHINE] --target-host root@ Will generate the facter.json hardware report for `[TARGET_HOST]` and place the result in facter.json for the given machine `[MACHINE]`. - - For more detailed information, visit: https://docs.clan.lol/guides/getting-started/configure/#machine-configuration - """ ), ) @@ -160,8 +154,10 @@ 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/create-installer/ -For more detailed information, visit: https://docs.clan.lol/guides/getting-started/hardware-report-physical +Further references: + +- https://docs.clan.lol/guides/getting-started/deploy-to-physical-machine/ +- https://docs.clan.lol/guides/getting-started/deploy-to-virtual-machine/ """ ), formatter_class=argparse.RawTextHelpFormatter, diff --git a/templates/clan/flake-parts/flake.nix b/templates/clan/flake-parts/flake.nix index 722e5dc3c..05cc56068 100644 --- a/templates/clan/flake-parts/flake.nix +++ b/templates/clan/flake-parts/flake.nix @@ -20,7 +20,7 @@ inputs.clan-core.flakeModules.default ]; - # https://docs.clan.lol/guides/getting-started/flake-parts/ + # https://docs.clan.lol/guides/flake-parts clan = { imports = [ ./clan.nix ]; };