diff --git a/clanModules/syncthing/README.md b/clanModules/syncthing/README.md index bd0ffdc3e..c83f7ed66 100644 --- a/clanModules/syncthing/README.md +++ b/clanModules/syncthing/README.md @@ -19,7 +19,7 @@ We recommend configuring this module as an sync-service through the provided opt - **Share Folders**: Select folders to share with connected devices and configure permissions and synchronization parameters. !!! info - Clan automatically discovers other devices. Automatic discovery requires one machine to be an [introducer](#clan.syncthing.introducer) + Clan automatically discovers other devices. Automatic discovery requires one machine to be an [introducer](#clansyncthingintroducer) If that is not the case you can add the other device by its Device ID manually. You can find and share Device IDs under the "Add Device" button in the Web GUI. (`127.0.0.1:8384`) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 936a20331..878dc74a4 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -39,24 +39,26 @@ exclude_docs: | /drafts/ nav: - - Get Started: - - index.md - - Installer: getting-started/installer.md - - Configure: getting-started/configure.md - - Secrets & Facts: getting-started/secrets.md - - Deploy Machine: getting-started/deploy.md - - Disk Encryption: getting-started/disk-encryption.md - - Mesh VPN: getting-started/mesh-vpn.md - - Backup & Restore: getting-started/backups.md - - Flake-parts: getting-started/flake-parts.md + - index.md - Manual: - Overview: manual/index.md + - Tutorials: + - Getting Started: + - getting-started/index.md + - Installer: getting-started/installer.md + - Configure: getting-started/configure.md + - Secrets & Facts: getting-started/secrets.md + - Deploy Machine: getting-started/deploy.md + - Disk Encryption: getting-started/disk-encryption.md + - Mesh VPN: getting-started/mesh-vpn.md + - Backup & Restore: getting-started/backups.md + - Flake-parts: getting-started/flake-parts.md - Include Machines: manual/include-machines.md - Inventory: manual/inventory.md - Secrets: manual/secrets.md - Secure Boot: manual/secure-boot.md - Contribute: manual/contribute.md - - Options: + - Reference: - Overview: reference/index.md - Clan Modules: - reference/clanModules/index.md diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py index bd1325e08..b186a5451 100644 --- a/docs/nix/render_options/__init__.py +++ b/docs/nix/render_options/__init__.py @@ -144,9 +144,8 @@ To use this module, import it like th: """ -clan_core_descr = """ClanCore delivers all the essential features for every clan. -It's always included in your setup, and you can customize your clan's behavior with the configuration [options](#module-options) provided below. - +clan_core_descr = """`clan.core` is always included in each machine `config`. +Your can customize your machines behavior with the configuration [options](#module-options) provided below. """ options_head = "\n## Module Options\n" diff --git a/docs/site/getting-started/configure.md b/docs/site/getting-started/configure.md index 43cf326c9..da41ccbdf 100644 --- a/docs/site/getting-started/configure.md +++ b/docs/site/getting-started/configure.md @@ -52,7 +52,7 @@ In the `flake.nix` file: === "**template using flake-parts**" - !!! info "See [Clan with flake-parts](./flake-parts.md) for help migrating to flake-parts." + !!! info "See [Clan with flake-parts](../manual/flake-parts.md) for help migrating to flake-parts." ```nix title="flake.nix" hl_lines="3" clan = { diff --git a/docs/site/getting-started/deploy.md b/docs/site/getting-started/deploy.md index 8ff89b6ca..81f7495ca 100644 --- a/docs/site/getting-started/deploy.md +++ b/docs/site/getting-started/deploy.md @@ -77,7 +77,7 @@ This process involves preparing a suitable hardware and disk partitioning config │ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion │ │ │ │Multicast DNS: nixos-installer.local │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ │ - │ Press 'Ctrl-C' for console access │ + │ Press 'Ctrl-C' for console access │ │ │ └─────────────────────────────────────────────────────────────────────────────────────┘ ``` @@ -100,7 +100,7 @@ This process involves preparing a suitable hardware and disk partitioning config ``` 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). + 3. See how to connect the installer medium to wlan [here](./installer.md#optional-connect-to-wifi-manually). 4. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted text__, images, ... basically anything that can be written in Markdown. diff --git a/docs/site/getting-started/index.md b/docs/site/getting-started/index.md new file mode 100644 index 000000000..9766cb520 --- /dev/null +++ b/docs/site/getting-started/index.md @@ -0,0 +1,109 @@ +# Getting Started + +Create your own clan with these initial steps and manage a fleet of machines with one single testable git repository! + +### Prerequisites + +=== "**Linux**" + + Clan depends on nix 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 + ``` + +=== "**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: + + ```nix + { nix.settings.experimental-features = [ "nix-command" "flakes" ]; } + ``` + +=== "**Other**" + + Clan doesn't offer dedicated support for other operating systems yet. + +### Step 1: Add Clan CLI to Your Shell + +Add the Clan CLI into your development workflow: + +```bash +nix shell git+https://git.clan.lol/clan/clan-core#clan-cli +``` + +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 + +Set the foundation of your Clan project by initializing it as follows: + +```bash +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. + +### Step 3: Verify the Project Structure + +Ensure that all project files exist by running: + +```bash +cd my-clan +tree +``` + +This should yield the following: + +``` { .console .no-copy } +. +├── flake.nix +├── machines +│   ├── jon +│   │   ├── configuration.nix +│   │   └── hardware-configuration.nix +│   └── sara +│   ├── configuration.nix +│   └── hardware-configuration.nix +└── modules + └── shared.nix + +5 directories, 9 files +``` + +```bash +clan machines list +``` + +``` { .console .no-copy } +jon +sara +``` + +!!! success + + You just successfully bootstrapped your first clan directory. + +--- + +### What's Next? + +- [**Installer**](./installer.md): Setting up new computers remotely is easy with an USB stick. + +--- diff --git a/docs/site/index.md b/docs/site/index.md index 7513349c9..d6f08ae57 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -1,109 +1,38 @@ -# Setup +# Home -Create your own clan with these initial steps and manage a fleet of machines with one single testable git repository! +## Welcome to **Clan**'s documentation -### Prerequisites +[Quickstart Guide](./getting-started/index.md){ .md-button } -=== "**Linux**" +## What's inside - Clan depends on nix installed on your system. Run the following command to install nix. +This documentation is structured into the following sections - ```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. +- :material-clock-fast:{ .lg .middle } __Set up in 15 minutes__ - ```bash - # /etc/nix/nix.conf or ~/.config/nix/nix.conf - experimental-features = nix-command flakes - ``` + --- -=== "**NixOS**" + Create your own clan and get everything + running in a couple of minutes. - If you run NixOS the `nix` binary is already installed. + [:octicons-arrow-right-24: Getting started](./getting-started/index.md) - You will also need to enable the `flakes` and `nix-commands` experimental features in your configuration.nix: +- :material-sign-direction:{ .lg .middle } __Manual__ - ```nix - { nix.settings.experimental-features = [ "nix-command" "flakes" ]; } - ``` + --- -=== "**Other**" + Instructions and explanations for practical Implementations ordered by Topic. - Clan doesn't offer dedicated support for other operating systems yet. + [:octicons-arrow-right-24: Manual](./manual/index.md) -### Step 1: Add Clan CLI to Your Shell +- :material-api:{ .lg .middle } __Reference__ -Add the Clan CLI into your development workflow: + --- -```bash -nix shell git+https://git.clan.lol/clan/clan-core#clan-cli -``` + Detailed Specification of Functions and APIs. -You can find reference documentation for the `clan` cli program [here](./reference/cli/index.md). + [:octicons-arrow-right-24: Reference](./reference/index.md) -Alternatively you can check out the help pages directly: -```terminalSession -clan --help -``` - -### Step 2: Initialize Your Project - -Set the foundation of your Clan project by initializing it as follows: - -```bash -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. - -### Step 3: Verify the Project Structure - -Ensure that all project files exist by running: - -```bash -cd my-clan -tree -``` - -This should yield the following: - -``` { .console .no-copy } -. -├── flake.nix -├── machines -│   ├── jon -│   │   ├── configuration.nix -│   │   └── hardware-configuration.nix -│   └── sara -│   ├── configuration.nix -│   └── hardware-configuration.nix -└── modules - └── shared.nix - -5 directories, 9 files -``` - -```bash -clan machines list -``` - -``` { .console .no-copy } -jon -sara -``` - -!!! success - - You just successfully bootstrapped your first clan directory. - ---- - -### What's Next? - -- [**Installer**](getting-started/installer.md): Setting up new computers remotely is easy with an USB stick. - ---- +
diff --git a/docs/site/getting-started/flake-parts.md b/docs/site/manual/flake-parts.md similarity index 100% rename from docs/site/getting-started/flake-parts.md rename to docs/site/manual/flake-parts.md diff --git a/docs/site/manual/index.md b/docs/site/manual/index.md index 089f490e4..e8ee03e11 100644 --- a/docs/site/manual/index.md +++ b/docs/site/manual/index.md @@ -1,11 +1,34 @@ -# Manual +# :material-book: Manual -Explore the Clan Framework in detail with comprehensive information on specific topics: +Instructions and explanations for practical Implementations ordered by Topics. + +## Tutorials + +**Learning-oriented adventures with a hands-on experience.** + +
+ +- :material-clock-fast:{ .lg .middle } __Set up in 15 minutes__ + + --- + + Create your own clan and get everything + running in minutes + + [:octicons-arrow-right-24: Getting started](../getting-started/index.md) + +
+ +## Guides + +**How-to Guides for achieving a certain goal or solving a specific issue.** - [Include Machines](./include-machines.md): Learn how Clan automatically includes machines and Nix files. -- [Secrets](./secrets.md): Learn how you can manage secrets +- [Secrets](./secrets.md): Learn how to manage secrets. -- [Inventory](./inventory.md): Access a distributed and editable version of the NixOS module system. +- [Inventory](./inventory.md): Distributed and editable version of the NixOS module system. -- [Contribute](./contribute.md): Discover how to set up a development environment to contribute to Clan! \ No newline at end of file +- [Flake-parts guide](./flake-parts.md): Use clan with [flake-parts](https://flake.parts/). + +- [Contribute](./contribute.md): Discover how to set up a development environment to contribute to Clan! diff --git a/docs/site/reference/index.md b/docs/site/reference/index.md index 191b394c4..3e4b55dca 100644 --- a/docs/site/reference/index.md +++ b/docs/site/reference/index.md @@ -1,6 +1,20 @@ -This section of the site provides an automatically generated overview of the available options and commands within the Clan Framework. +# :material-api: Overview + +This section of the site provides an **automatically extracted** overview of the available options and commands within the Clan Framework. + +--- - Learn how to use the [Clan CLI](./cli/index.md) - Explore available services and application [modules](./clanModules/index.md) - Discover [configuration options](./clan-core/index.md) that manage essential features -- Find descriptions of the [Nix interfaces](./nix-api/index.md) for defining a Clan \ No newline at end of file +- Find descriptions of the [Nix interfaces](./nix-api/index.md) for defining a Clan + +--- + +!!! Note + This documentation is always built for the main branch. + If you need documentation for a specific commit you can build it on your own + + ```bash + nix build 'git+https://git.clan.lol/clan/clan-core?ref=0324f4d4b87d932163f351e53b23b0b17f2b5e15#docs' + ``` diff --git a/lib/build-clan/interface.nix b/lib/build-clan/interface.nix index 2e11b531e..b33275165 100644 --- a/lib/build-clan/interface.nix +++ b/lib/build-clan/interface.nix @@ -8,7 +8,21 @@ in directory = lib.mkOption { type = types.path; default = self; - description = "The directory containing the clan subdirectory"; + defaultText = "Root directory of the flake"; + description = '' + The directory containing the clan. + + A typical directory structure could look like this: + + ``` + . + ├── flake.nix + ├── assets + ├── machines + ├── modules + └── sops + ``` + ''; }; specialArgs = lib.mkOption {