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

Merge pull request 'docs: misc clean up' (#3735) from push-kpzwvynvlszo into main

Browse Source 
Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/3735
This commit is contained in:
Michael Hoang
2025-05-21 14:12:47 +00:00
parent 04ca72f5b5 5bc6126873
commit f8cf9fa172
15 changed files with 73 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
.gitignore vendored
View File

@@ -1,24 +1,24 @@
.direnv
**/.nixos-test-history
***/.hypothesis
.nixos-test-history
.hypothesis
out.log
.coverage.*
**/qubeclan
qubeclan
pkgs/repro-hook
**/testdir
testdir
democlan
example_clan
**/result
result*
/pkgs/clan-cli/clan_lib/nixpkgs
/pkgs/clan-cli/clan_cli/webui/assets
nixos.qcow2
**/*.glade~
*.glade~
/docs/out
/pkgs/clan-cli/clan_lib/select
**/.local.env
.local.env
# MacOS stuff
**/.DS_store
# macOS stuff
.DS_Store
# dream2nix
.dream2nix

8
docs/mkdocs.yml
View File

@@ -48,9 +48,9 @@ nav:
- Home: index.md
- Guides:
- Getting Started:
- Setup Clan: guides/getting-started/index.md
- Creating Your First Clan: guides/getting-started/index.md
- Create Installer: guides/getting-started/installer.md
- Add Machines: guides/getting-started/configure.md
- Add Machines: guides/getting-started/add-machines.md
- Secrets & Facts: guides/getting-started/secrets.md
- Deploy Machine: guides/getting-started/deploy.md
- Continuous Integration: guides/getting-started/check.md
@@ -60,7 +60,7 @@ nav:
- Backup & Restore: guides/backups.md
- Vars Backend: guides/vars-backend.md
- Facts Backend: guides/secrets.md
- Autoincludes: guides/adding-machines.md
- Adding more machines: guides/more-machines.md
- Inventory:
- Inventory: guides/inventory.md
- Secure Boot: guides/secure-boot.md
@@ -77,7 +77,7 @@ nav:
- Migrate existing Flakes: guides/migrations/migration-guide.md
- Migrate inventory Services: guides/migrations/migrate-inventory-services.md
- Facts Vars Migration: guides/migrations/migration-facts-vars.md
- MacOS: guides/macos.md
- macOS: guides/macos.md
- Reference:
- Overview: reference/index.md
- Clan Services:

2
docs/nix/render_options/__init__.py
View File

@@ -576,7 +576,7 @@ def produce_clan_modules_docs() -> None:
!!! Warning "Deprecated"
The `{module_name}` module is deprecated.*
Use: [clanServices/{module_name}](../clanServices/{module_name}.md) instead
Use [clanServices/{module_name}](../clanServices/{module_name}.md) instead
"""
else:
output += f"""

2
docs/site/guides/contributing/debugging.md
View File

@@ -112,7 +112,7 @@ You can execute every test separately by following the tree path `nix run .#chec
## Test Locally in Devshell with Breakpoints
To test the cli locally in a development environment and set breakpoints for debugging, follow these steps:
To test the CLI locally in a development environment and set breakpoints for debugging, follow these steps:
1. Run the following command to execute your tests and allow for debugging with breakpoints:
```bash

2
docs/site/guides/contributing/testing.md
View File

@@ -113,7 +113,7 @@ rg self.clanLib.test.containerTest
## Python tests via pytest
Since the clan cli is written in python, the `pytest` framework is used to define unit tests and integration tests via python
Since the Clan CLI is written in python, the `pytest` framework is used to define unit tests and integration tests via python
Due to superior efficiency,

12
docs/site/guides/getting-started/configure.md → docs/site/guides/getting-started/add-machines.md
View File

@@ -1,20 +1,20 @@
Managing machine configurations can be done in the following ways:
- writing `nix` expressions in a `flake.nix` file,
- placing `autoincluded` files into your machine directory,
- writing Nix expressions in a `flake.nix` file
- placing `autoincluded` files into your machine directory
Clan currently offers the following methods to configure machines:
!!! Success "Recommended for nix people"
!!! Success "Recommended for advanced Nix users"
- flake.nix (i.e. via `buildClan`)
- `machine` argument
- `inventory` argument
- machines/`machine_name`/configuration.nix (`autoincluded` if it exists)
- machines/`machine_name`/configuration.nix (automatically included if it exists)
See the complete [list](../../guides/adding-machines.md#automatic-registration) of auto-loaded files.
See the complete [list](../../guides/more-machines.md#automatic-registration) of auto-loaded files.
???+ Note "Used by CLI & UI"
@@ -124,7 +124,7 @@ Adding or configuring a new machine requires two simple steps:
!!! Info "Replace `__YOUR_SSH_KEY__` with your personal key, like `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILoMI0NC5eT9pHlQExrvR5ASV3iW9+BXwhfchq0smXUJ jon@jon-desktop`"
You can also create additional machines using the cli:
You can also create additional machines using the CLI:
```
$ clan machines create <machinename>

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

@@ -8,7 +8,7 @@ Now that you have created a new machine, we will walk through how to install it.
=== "**Physical Hardware**"
- [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 [configuration guide](./configure.md)
- [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](installer.md)
@@ -21,7 +21,7 @@ Now that you have created a new machine, we will walk through how to install it.
=== "**Cloud VMs**"
- [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 [configuration guide](./configure.md)
- [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.
!!! Steps
@@ -171,7 +171,7 @@ clan machines update
If the machine does not have enough resources to run the NixOS evaluation or build itself,
it is also possible to specify a build host instead.
During an update, the cli will ssh into the build host and run `nixos-rebuild` from there.
During an update, the CLI will SSH into the build host and run `nixos-rebuild` from there.
```{.nix hl_lines="5" .no-copy}

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

@@ -1,41 +1,41 @@
# :material-clock-fast: Getting Started
Ready to create your own clan and manage a fleet of machines? Follow these simple steps to get started.
Ready to create your own Clan and manage a fleet of machines? Follow these simple steps to get started.
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!
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
=== "**Linux**"
Clan depends on nix installed on your system. Run the following command to install nix.
Clan requires Nix to be 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
```
If you already have installed Nix, make sure you have the `nix-command` and `flakes` configuration enabled in your ~/.config/nix/nix.conf.
The determinate installer already comes with this configuration by default.
```bash
# /etc/nix/nix.conf or ~/.config/nix/nix.conf
experimental-features = nix-command flakes
```
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`.
=== "**NixOS**"
If you run NixOS the `nix` binary is already installed.
You will also need to enable the `flakes` and `nix-commands` experimental features in your configuration.nix:
You will also need to enable the `nix-command` and `flakes` experimental features in your `configuration.nix`:
```nix
{ nix.settings.experimental-features = [ "nix-command" "flakes" ]; }
```
=== "**Other**"
=== "**macOS**"
Clan doesn't offer dedicated support for other operating systems yet.
Clan requires Nix to be 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
```
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
@@ -45,7 +45,7 @@ Add the Clan CLI into your development workflow:
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).
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
@@ -56,7 +56,7 @@ clan --help
If you want to migrate an existing project, follow this [guide](../migrations/migration-guide.md).
Set the foundation of your Clan project by initializing it as follows:
Set the foundation of your Clan project by initializing it by running:
```bash
clan flakes create my-clan
@@ -92,19 +92,22 @@ This should yield the following:
5 directories, 9 files
```
??? info "Recommended way of sourcing the `clan` cli tool"
The default template also adds the `clan` cli tool to the development shell.
Meaning you can get the exact version you need directly from the folder
??? info "Recommended way of sourcing the `clan` CLI tool"
The default template adds the `clan` CLI tool to the development shell.
This means that you can access the `clan` CLI tool directly from the folder
you are in right now.
In the `my-clan` directory run the following command:
In the `my-clan` directory, run the following command:
```
nix develop
```
That way you will have the tool available in the shell environment.
We also recommend setting up [direnv](https://direnv.net/) for your shell, for a more convenient
experience.
This will ensure the `clan` CLI tool is available in your shell environment.
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
@@ -118,5 +121,5 @@ sara
!!! success
You just successfully bootstrapped your first clan directory.
You just successfully bootstrapped your first Clan.

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

@@ -3,7 +3,7 @@
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 [Configure Machines](configure.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 using a cloud provider's virtual machine (VM), you can skip this section and go directly to the [Add Machines](add-machines.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.

4
docs/site/guides/inventory.md
View File

@@ -19,7 +19,7 @@ See also: [Inventory API Documentation](../reference/nix-api/inventory.md)
## Prerequisites
- [x] [Add machines](./adding-machines.md) to your clan.
- [x] [Add multiple machines](./more-machines.md) to your Clan.
## Services
@@ -29,7 +29,7 @@ See each [modules documentation](../reference/clanModules/index.md) for its avai
### Adding services to machines
A service can be added to one or multiple machines via `Roles`. clan's `Role` interface provide sane defaults for a module this allows the module author to reduce the configuration overhead to a minimum.
A service can be added to one or multiple machines via `Roles`. Clan's `Role` interface provide sane defaults for a module this allows the module author to reduce the configuration overhead to a minimum.
Each service can still be customized and configured according to the modules options.

4
docs/site/guides/macos.md
View File

@@ -6,8 +6,8 @@ This guide explains how to manage macOS machines using Clan.
Currently, Clan supports the following features for macOS:
- `clan machines update` for existing [nix-darwin](https://github.com/nix-darwin/nix-darwin) installations.
- Support for [vars](../guides/vars-backend.md).
- `clan machines update` for existing [nix-darwin](https://github.com/nix-darwin/nix-darwin) installations
- Support for [vars](../guides/vars-backend.md)
## Step 1: Add Your Machine to Your Clan Flake

0
docs/site/guides/adding-machines.md → docs/site/guides/more-machines.md
View File

10
docs/site/guides/vars-backend.md
View File

@@ -10,13 +10,13 @@ In this example, we will guide you through automating that interaction using cla
For a more general explanation of what clan vars are and how it works, see the intro of the [Reference Documentation for vars](../reference/clan.core/vars.md)
This guide assumes
- clan is set up already (see [Getting Started](../guides/getting-started/index.md))
- a machine has been added to the clan (see [Adding Machines](./adding-machines.md))
- Clan is set up already (see [Getting Started](../guides/getting-started/index.md))
- a machine has been added to the clan (see [Adding Machines](./more-machines.md))
This section will walk you through the following steps:
1. declare a `generator` in the machine's nixos configuration
2. inspect the status via the clan cli
2. inspect the status via the Clan CLI
3. generate the vars
4. observer the changes
5. update the machine
@@ -147,5 +147,5 @@ Updated var root-password/password-hash
## Further Reading
- [Reference Documentation for `clan.core.vars` nixos options](../reference/clan.core/vars.md)
- [Reference Documentation for the `clan vars` cli command](../reference/cli/vars.md)
- [Reference Documentation for `clan.core.vars` NixOS options](../reference/clan.core/vars.md)
- [Reference Documentation for the `clan vars` CLI command](../reference/cli/vars.md)

16
docs/site/index.md
View File

@@ -14,7 +14,7 @@ hide:
<div class="grid cards" markdown>
- [Autoincludes](./guides/adding-machines.md)
- [Adding more machines](./guides/more-machines.md)
---
@@ -24,7 +24,7 @@ hide:
---
Learn how to manage secrets with facts.
Learn how to manage secrets with vars.
- [Inventory](./guides/inventory.md)
@@ -36,7 +36,7 @@ hide:
---
Use clan with [https://flake.parts/]()
Use Clan with [https://flake.parts/]()
- [Contribute](./guides/contributing/CONTRIBUTING.md)
@@ -44,12 +44,12 @@ hide:
Discover how to set up a development environment to contribute to Clan!
- [macOS machines](./guides/macos.md)
---
Manage macOS machines with nix-darwin
- [MacOS machines](./guides/macos.md)
</div>
## API Reference
@@ -58,11 +58,11 @@ hide:
<div class="grid cards" markdown>
- [Cli Reference](./reference/cli/index.md)
- [CLI Reference](./reference/cli/index.md)
---
The `clan` cli command
The `clan` CLI command
- [Service Modules](./reference/clanServices/index.md)
@@ -84,7 +84,7 @@ hide:
An overview of available clanModules
!!! Example "Those will get deprecated soon"
!!! Example "These will be deprecated soon"
</div>

8
pkgs/clan-cli/README.md
View File

@@ -1,17 +1,17 @@
# clan-cli
The clan-cli contains the command line interface
The Clan CLI contains the command line interface.
## Hacking on the cli
## Hacking on the CLI
We recommend setting up [direnv](https://direnv.net/) to load the development with nix.
We recommend setting up [direnv](https://direnv.net/) to load the development with Nix.
If you do not have it set up you can also use `nix develop` directly like this:
```
use flake .#clan-cli --builders ''
```
After you can use the local bin wrapper to test things in the cli:
After you can use the local bin wrapper to test things in the CLI:
```
./bin/clan