From 030b04655278e672be0e0463eddaf3ab623f1c9c Mon Sep 17 00:00:00 2001 From: Qubasa Date: Sat, 18 Jan 2025 10:00:56 +0700 Subject: [PATCH] Reapply "docs: Document imports dir. Remove What's next sections everywhere. Merge guide overview and hompage view." This reverts commit ba517f56b3db7fe68e4e6df6aab42761d61bdc14. --- docs/CONTRIBUTING.md | 35 ++++++++- docs/mkdocs.yml | 13 ++-- docs/site/getting-started/backups.md | 6 +- docs/site/getting-started/configure.md | 9 --- docs/site/getting-started/deploy.md | 9 --- docs/site/getting-started/index.md | 7 -- docs/site/getting-started/installer.md | 9 +-- docs/site/getting-started/mesh-vpn.md | 1 - docs/site/getting-started/secrets.md | 6 -- docs/site/index.md | 76 +++++++++++++++---- docs/site/manual/adding-machines.md | 13 +++- docs/site/manual/debugging.md | 4 - docs/site/manual/disk-templates.md | 2 - docs/site/manual/flake-parts.md | 1 - docs/site/manual/index.md | 66 ---------------- docs/site/manual/inventory.md | 1 - docs/site/manual/migration-guide.md | 20 ++--- docs/site/manual/repo-layout.md | 35 --------- ...t-password-via-vars.md => vars-backend.md} | 5 +- 19 files changed, 126 insertions(+), 192 deletions(-) delete mode 100644 docs/site/manual/index.md rename docs/site/manual/{manage-root-password-via-vars.md => vars-backend.md} (98%) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 9b6910ee6..ff3c92390 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,4 +1,5 @@ -# Contributing +# Contributing to Clan + **Continuous Integration (CI)**: Each pull request gets automatically tested by gitea. If any errors are detected, it will block pull requests until they're resolved. @@ -94,12 +95,40 @@ Let's get your development environment up and running: merge-after-ci --reviewers Mic92 Lassulus Qubasa ``` +## Related Projects +- **Data Mesher**: [dm](https://git.clan.lol/clan/dm) +- **Nixos Facter**: [nixos-facter](https://github.com/nix-community/nixos-facter) +- **Nixos Anywhere**: [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) +- **Disko**: [disko](https://github.com/nix-community/disko) -### Whats Next? +## Fixing Bugs or Adding Features in Clan-CLI -Please look into the [debugging](./debugging.md) guide next! +If you have a bug fix or feature that involves a related project, clone the relevant repository and replace its invocation in your local setup. +For instance, if you need to update `nixos-anywhere` in clan-cli, find its usage: + +```python +run( + nix_shell( + ["nixpkgs#nixos-anywhere"], + cmd, + ), + RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True), +) +``` + +You can replace `"nixpkgs#nixos-anywhere"` with your local path: + +```python +run( + nix_shell( + ["#nixos-anywhere"], + cmd, + ), + RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True), +) +``` # Standards diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index c6c74118d..9131a8fdd 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -43,20 +43,19 @@ exclude_docs: | nav: - Home: index.md - Getting Started: - - Getting Started: getting-started/index.md - - Installer: getting-started/installer.md - - Configure: getting-started/configure.md + - Setup Clan: getting-started/index.md + - Create Installer: getting-started/installer.md + - Add Machines: getting-started/configure.md - Secrets & Facts: getting-started/secrets.md - Deploy Machine: getting-started/deploy.md - Guides: - - Overview: manual/index.md - - Manage passwords using vars: manual/manage-root-password-via-vars.md - Disk Encryption: getting-started/disk-encryption.md - Mesh VPN: getting-started/mesh-vpn.md - Backup & Restore: getting-started/backups.md - - Adding Machines: manual/adding-machines.md + - Vars Backend: manual/vars-backend.md + - Facts Backend: manual/secrets.md + - Autoincludes: manual/adding-machines.md - Inventory: manual/inventory.md - - Secrets: manual/secrets.md - Secure Boot: manual/secure-boot.md - Flake-parts: manual/flake-parts.md - Authoring: diff --git a/docs/site/getting-started/backups.md b/docs/site/getting-started/backups.md index 90fb8a628..ad72eabf8 100644 --- a/docs/site/getting-started/backups.md +++ b/docs/site/getting-started/backups.md @@ -1,6 +1,4 @@ -# Backups - -## Introduction to Backups +# Introduction to Backups When you're managing your own services, creating regular backups is crucial to ensure your data's safety. This guide introduces you to Clan's built-in backup functionalities. @@ -9,8 +7,6 @@ We might add more options in the future, but for now, let's dive into how you ca ## Backing Up Locally with Localbackup -### What is Localbackup? - Localbackup lets you backup your data onto physical storage devices connected to your computer, such as USB hard drives or network-attached storage. It uses a tool called rsnapshot for this purpose. diff --git a/docs/site/getting-started/configure.md b/docs/site/getting-started/configure.md index 3dc2e190d..88ee6a799 100644 --- a/docs/site/getting-started/configure.md +++ b/docs/site/getting-started/configure.md @@ -1,4 +1,3 @@ -# Configuration - How to configure clan with your own machines Managing machine configurations can be done in the following ways: @@ -208,11 +207,3 @@ If you only want to setup a single machine at this point, you can delete `sara` ``` git rm ./machines/sara ``` - ---- - -## What's next? - -- [Secrets & Facts](secrets.md): Setting up secrets with sops-nix - ---- diff --git a/docs/site/getting-started/deploy.md b/docs/site/getting-started/deploy.md index 8b2ebb99e..719ca3ef0 100644 --- a/docs/site/getting-started/deploy.md +++ b/docs/site/getting-started/deploy.md @@ -1,4 +1,3 @@ -# Deploy Machine Integrating a new machine into your Clan environment is an easy yet flexible process, allowing for a straight forward management of multiple NixOS configurations. @@ -215,12 +214,4 @@ buildClan { This is useful for machines that are not always online or are not part of the regular update cycle. ---- - -## What's next ? - -- [**Disk Encryption**](./disk-encryption.md): Configure disk encryption with remote decryption -- [**Mesh VPN**](./mesh-vpn.md): Configuring a secure mesh network. - ---- diff --git a/docs/site/getting-started/index.md b/docs/site/getting-started/index.md index b46e74d2e..62735d31a 100644 --- a/docs/site/getting-started/index.md +++ b/docs/site/getting-started/index.md @@ -105,10 +105,3 @@ sara 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/getting-started/installer.md b/docs/site/getting-started/installer.md index 0a967677e..1a1a2125d 100644 --- a/docs/site/getting-started/installer.md +++ b/docs/site/getting-started/installer.md @@ -1,4 +1,4 @@ -# Installer +# Create an Installer Image Our installer image simplifies the process of performing remote installations. @@ -197,10 +197,3 @@ Press ++ctrl+d++ to exit `IWD`. You're all set up ---- - -## What's next? - -- [Configure Machines](configure.md): Customize machine configuration - ---- diff --git a/docs/site/getting-started/mesh-vpn.md b/docs/site/getting-started/mesh-vpn.md index 35c84d6d4..8f2c68d2e 100644 --- a/docs/site/getting-started/mesh-vpn.md +++ b/docs/site/getting-started/mesh-vpn.md @@ -1,4 +1,3 @@ -# Mesh VPN This guide provides detailed instructions for configuring [ZeroTier VPN](https://zerotier.com) within Clan. Follow the diff --git a/docs/site/getting-started/secrets.md b/docs/site/getting-started/secrets.md index 4769dfe68..baf112db7 100644 --- a/docs/site/getting-started/secrets.md +++ b/docs/site/getting-started/secrets.md @@ -1,4 +1,3 @@ -# Secrets / Facts Clan enables encryption of secrets (such as passwords & keys) ensuring security and ease-of-use among users. @@ -84,8 +83,3 @@ This command helps ensure that your system configuration is correct and free fro You can integrate this step into your [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) workflow to ensure that only valid Nix configurations are merged into your codebase. - -## What's next? - -- [Deployment](deploy.md): How to remotely deploy your machine -- Full [Secrets](../manual/secrets.md) guide If you want to know more about how to save and share passwords in your clan diff --git a/docs/site/index.md b/docs/site/index.md index 39785e898..d51dc50f4 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -4,13 +4,13 @@ hide: - toc --- -# :material-home: Welcome to **Clan**'s awesome documentation +# :material-home: Welcome to **Clan**'s documentation [Getting Started](./getting-started/index.md){ .md-button } -## What's inside +## Tutorials -This documentation is structured into the following sections +**Learning-oriented adventures with a hands-on experience.**
@@ -19,25 +19,69 @@ This documentation is structured into the following sections --- Create your own clan and get everything - running in a couple of minutes. + running in minutes [:octicons-arrow-right-24: Getting started](./getting-started/index.md) - -- :material-sign-direction:{ .lg .middle } __Guides__ +- :fontawesome-solid-user-group:{ .lg .middle } __Authoring Modules__ --- - Instructions and explanations for practical Implementations ordered by Topic. + Create clanModules that can be reused by the community. - [:octicons-arrow-right-24: Guides](./manual/index.md) - -- :material-api:{ .lg .middle } __Reference__ - - --- - - Detailed Specification of Functions and APIs. - - [:octicons-arrow-right-24: Reference](./reference/index.md) + [:octicons-arrow-right-24: Authoring clanModules](./clanmodules/index.md)
+ +## :material-book: Guides + +**How-to Guides for achieving a certain goal or solving a specific issue.** + +
+ +- [Autoincludes](./manual/adding-machines.md) + + --- + + Learn how Clan automatically includes machines and Nix files. + +- [Vars Backend](./manual/vars-backend.md) + + --- + + Learn how to manage secrets with facts. + +- [Inventory](./manual/inventory.md) + + --- + + Clan's declaration format for running **services** on one or multiple **machines**. + +- [Flake-parts](./manual/flake-parts.md) + + --- + + Use clan with [https://flake-parts.dev]() + +- [Contribute](./manual/contribute.md) + + --- + + Discover how to set up a development environment to contribute to Clan! + +
+ +## API Reference + +**Auto generated API Documentation** + +
+ +- [Reference Overview](./reference/index.md) + + --- + + Learn how to interface with Clan programmatically + + +
\ No newline at end of file diff --git a/docs/site/manual/adding-machines.md b/docs/site/manual/adding-machines.md index 07c16db9b..b1830b7a0 100644 --- a/docs/site/manual/adding-machines.md +++ b/docs/site/manual/adding-machines.md @@ -1,4 +1,3 @@ -# Adding Machines Clan has two general methods of adding machines: @@ -18,6 +17,18 @@ Every folder `machines/{machineName}` will be registered automatically as a Clan - [x] `machines/{machineName}/facter.json` Automatically configured, for further information see [nixos-facter](https://clan.lol/blog/nixos-facter/) - [x] `machines/{machineName}/disko.nix` Automatically loaded, for further information see the [disko docs](https://github.com/nix-community/disko/blob/master/docs/quickstart.md). + +## Automatic Imports + +The `buildClan` function will automatically import modules if a directory named `/imports` exists within the Clan. Below are the conditions for importing inventory modules: + +- **Inventory Modules**: Modules located in `/imports/inventory` will be automatically imported. Note that only inventory-compatible modules can be used in this location. To be compatible, a module must contain a `roles` folder. + +- **Adding a Module**: To add a module, such as `mymodule`, create a dedicated directory at `/imports/inventory/mymodule`, ensuring that it includes a `roles` folder. + +For further details on creating Clan modules, please refer to the [Authoring Clan Modules](../clanmodules/index.md) section. + + ## Manual declaration Machines can also be added manually under `buildClan`, `clan.*` in flake-parts or via [`inventory`](../manual/inventory.md). diff --git a/docs/site/manual/debugging.md b/docs/site/manual/debugging.md index a112d5377..66ddd0c4c 100644 --- a/docs/site/manual/debugging.md +++ b/docs/site/manual/debugging.md @@ -1,4 +1,3 @@ -# Debugging Here are some methods for debugging and testing the clan-cli @@ -152,6 +151,3 @@ If you need to inspect the Nix sandbox while running tests, follow these steps: Or you can also use the [nix breakpoint hook](https://nixos.org/manual/nixpkgs/stable/#breakpointhook) -### What's next? - -Please look into the [repo layout](./repo-layout.md) guide next! diff --git a/docs/site/manual/disk-templates.md b/docs/site/manual/disk-templates.md index b8dc3598d..78da39a58 100644 --- a/docs/site/manual/disk-templates.md +++ b/docs/site/manual/disk-templates.md @@ -1,5 +1,3 @@ -# Disk Templates - !!! Danger ":fontawesome-solid-road-barrier: Under Construction :fontawesome-solid-road-barrier:" Currently under construction use with caution diff --git a/docs/site/manual/flake-parts.md b/docs/site/manual/flake-parts.md index 378bcf6a0..bbfb81cf9 100644 --- a/docs/site/manual/flake-parts.md +++ b/docs/site/manual/flake-parts.md @@ -1,4 +1,3 @@ -# Clan with `flake-parts` Clan supports integration with [flake.parts](https://flake.parts/) a tool which allows composing nixos modules in a modular way. diff --git a/docs/site/manual/index.md b/docs/site/manual/index.md deleted file mode 100644 index 1b623b10a..000000000 --- a/docs/site/manual/index.md +++ /dev/null @@ -1,66 +0,0 @@ -# :material-book: Guides - -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) - -- :fontawesome-solid-user-group:{ .lg .middle } __Authoring Modules__ - - --- - - Create clanModules that can be reused by the community. - - [:octicons-arrow-right-24: Authoring clanModules](../clanmodules/index.md) - -
- -## Guides - -**How-to Guides for achieving a certain goal or solving a specific issue.** - -
- -- [Machines](./adding-machines.md) - - --- - - Learn how Clan automatically includes machines and Nix files. - -- [Secrets](./secrets.md) - - --- - - Learn how to manage secrets. - -- [Inventory](./inventory.md) - - --- - - Clan's declaration format for running **services** on one or multiple **machines**. - -- [Flake-parts](./flake-parts.md) - - --- - - Use clan with [https://flake-parts.dev]() - -- [Contribute](./contribute.md) - - --- - - Discover how to set up a development environment to contribute to Clan! - -
\ No newline at end of file diff --git a/docs/site/manual/inventory.md b/docs/site/manual/inventory.md index 0ee7cfdad..5b861d13a 100644 --- a/docs/site/manual/inventory.md +++ b/docs/site/manual/inventory.md @@ -1,4 +1,3 @@ -# Inventory `Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries. diff --git a/docs/site/manual/migration-guide.md b/docs/site/manual/migration-guide.md index 2c8da831c..04b365b70 100644 --- a/docs/site/manual/migration-guide.md +++ b/docs/site/manual/migration-guide.md @@ -1,16 +1,16 @@ # Migrate existing NixOS configurations -This guide will help you migrate your existing Nix configurations into Clan. Keep -in mind, though, this approach can be trickier and might lead to bugs or -unexpected issues. We recommend following the Getting Started guide first. Once -you have a working setup, you can easily transfer your Nix configurations over. +This guide will help you migrate your existing Nix configurations into Clan. -!!! Danger - **Back up your existing configuration!** - Before you start, it is strongly recommended to back up your existing - configuration in any form you see fit. If you use version control to manage - your configuration changes, it is also a good idea to follow the migration - guide in a separte branch until everything works as expected. +!!! Warning + Migrating instead of starting new can be trickier and might lead to bugs or + unexpected issues. We recommend following the [Getting Started](../getting-started/index.md) guide first. Once you have a working setup, you can easily transfer your Nix configurations over. + +## Back up your existing configuration! +Before you start, it is strongly recommended to back up your existing +configuration in any form you see fit. If you use version control to manage +your configuration changes, it is also a good idea to follow the migration +guide in a separte branch until everything works as expected. ## Starting Point diff --git a/docs/site/manual/repo-layout.md b/docs/site/manual/repo-layout.md index 5209e75de..56864c95d 100644 --- a/docs/site/manual/repo-layout.md +++ b/docs/site/manual/repo-layout.md @@ -1,4 +1,3 @@ -# Repo Layout Guide This guide will help you navigate the codebase and locate key files: @@ -24,37 +23,3 @@ $ tree -L 1 To dive into infrastructure, check out our clan infra repo: [clan-infra](https://git.clan.lol/clan/clan-infra). Please provide us with your public SOPS key so we can add you as an admin. -## Related Projects - -- **Data Mesher**: [dm](https://git.clan.lol/clan/dm) -- **Nixos Facter**: [nixos-facter](https://github.com/nix-community/nixos-facter) -- **Nixos Anywhere**: [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) -- **Disko**: [disko](https://github.com/nix-community/disko) - -## Fixing Bugs or Adding Features in Clan-CLI - -If you have a bug fix or feature that involves a related project, clone the relevant repository and replace its invocation in your local setup. - -For instance, if you need to update `nixos-anywhere` in clan-cli, find its usage: - -```python -run( - nix_shell( - ["nixpkgs#nixos-anywhere"], - cmd, - ), - RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True), -) -``` - -You can replace `"nixpkgs#nixos-anywhere"` with your local path: - -```python -run( - nix_shell( - ["#nixos-anywhere"], - cmd, - ), - RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True), -) -``` diff --git a/docs/site/manual/manage-root-password-via-vars.md b/docs/site/manual/vars-backend.md similarity index 98% rename from docs/site/manual/manage-root-password-via-vars.md rename to docs/site/manual/vars-backend.md index 5dde4604d..9575746e6 100644 --- a/docs/site/manual/manage-root-password-via-vars.md +++ b/docs/site/manual/vars-backend.md @@ -1,4 +1,7 @@ -# Managing the root password declaratively using `vars` + +!!! Note + Vars is the new secret backend that will soon replace the Facts backend + Defining a linux user's password via the nixos configuration previously required running `mkpasswd ...` and then copying the hash back into the nix configuration.