diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index ff3c92390..9b6910ee6 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,5 +1,4 @@ -# Contributing to Clan - +# Contributing **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. @@ -95,40 +94,12 @@ 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) -## Fixing Bugs or Adding Features in Clan-CLI +### Whats 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. +Please look into the [debugging](./debugging.md) guide next! -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 9131a8fdd..c6c74118d 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -43,19 +43,20 @@ exclude_docs: | nav: - Home: index.md - Getting Started: - - Setup Clan: getting-started/index.md - - Create Installer: getting-started/installer.md - - Add Machines: getting-started/configure.md + - 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 - 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 - - Vars Backend: manual/vars-backend.md - - Facts Backend: manual/secrets.md - - Autoincludes: manual/adding-machines.md + - Adding Machines: 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 ad72eabf8..90fb8a628 100644 --- a/docs/site/getting-started/backups.md +++ b/docs/site/getting-started/backups.md @@ -1,4 +1,6 @@ -# Introduction to Backups +# 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. @@ -7,6 +9,8 @@ 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 88ee6a799..3dc2e190d 100644 --- a/docs/site/getting-started/configure.md +++ b/docs/site/getting-started/configure.md @@ -1,3 +1,4 @@ +# Configuration - How to configure clan with your own machines Managing machine configurations can be done in the following ways: @@ -207,3 +208,11 @@ 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 719ca3ef0..8b2ebb99e 100644 --- a/docs/site/getting-started/deploy.md +++ b/docs/site/getting-started/deploy.md @@ -1,3 +1,4 @@ +# 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. @@ -214,4 +215,12 @@ 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 62735d31a..b46e74d2e 100644 --- a/docs/site/getting-started/index.md +++ b/docs/site/getting-started/index.md @@ -105,3 +105,10 @@ 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 1a1a2125d..0a967677e 100644 --- a/docs/site/getting-started/installer.md +++ b/docs/site/getting-started/installer.md @@ -1,4 +1,4 @@ -# Create an Installer Image +# Installer Our installer image simplifies the process of performing remote installations. @@ -197,3 +197,10 @@ 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 8f2c68d2e..35c84d6d4 100644 --- a/docs/site/getting-started/mesh-vpn.md +++ b/docs/site/getting-started/mesh-vpn.md @@ -1,3 +1,4 @@ +# 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 baf112db7..4769dfe68 100644 --- a/docs/site/getting-started/secrets.md +++ b/docs/site/getting-started/secrets.md @@ -1,3 +1,4 @@ +# Secrets / Facts Clan enables encryption of secrets (such as passwords & keys) ensuring security and ease-of-use among users. @@ -83,3 +84,8 @@ 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 d51dc50f4..39785e898 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -4,13 +4,13 @@ hide: - toc --- -# :material-home: Welcome to **Clan**'s documentation +# :material-home: Welcome to **Clan**'s awesome documentation [Getting Started](./getting-started/index.md){ .md-button } -## Tutorials +## What's inside -**Learning-oriented adventures with a hands-on experience.** +This documentation is structured into the following sections
@@ -19,69 +19,25 @@ hide: --- Create your own clan and get everything - running in minutes + running in a couple of minutes. [:octicons-arrow-right-24: Getting started](./getting-started/index.md) -- :fontawesome-solid-user-group:{ .lg .middle } __Authoring Modules__ + +- :material-sign-direction:{ .lg .middle } __Guides__ --- - Create clanModules that can be reused by the community. + Instructions and explanations for practical Implementations ordered by Topic. - [:octicons-arrow-right-24: Authoring clanModules](./clanmodules/index.md) + [: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)
- -## :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 b1830b7a0..07c16db9b 100644 --- a/docs/site/manual/adding-machines.md +++ b/docs/site/manual/adding-machines.md @@ -1,3 +1,4 @@ +# Adding Machines Clan has two general methods of adding machines: @@ -17,18 +18,6 @@ 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 66ddd0c4c..a112d5377 100644 --- a/docs/site/manual/debugging.md +++ b/docs/site/manual/debugging.md @@ -1,3 +1,4 @@ +# Debugging Here are some methods for debugging and testing the clan-cli @@ -151,3 +152,6 @@ 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 78da39a58..b8dc3598d 100644 --- a/docs/site/manual/disk-templates.md +++ b/docs/site/manual/disk-templates.md @@ -1,3 +1,5 @@ +# 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 bbfb81cf9..378bcf6a0 100644 --- a/docs/site/manual/flake-parts.md +++ b/docs/site/manual/flake-parts.md @@ -1,3 +1,4 @@ +# 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 new file mode 100644 index 000000000..1b623b10a --- /dev/null +++ b/docs/site/manual/index.md @@ -0,0 +1,66 @@ +# :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 5b861d13a..0ee7cfdad 100644 --- a/docs/site/manual/inventory.md +++ b/docs/site/manual/inventory.md @@ -1,3 +1,4 @@ +# Inventory `Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries. diff --git a/docs/site/manual/vars-backend.md b/docs/site/manual/manage-root-password-via-vars.md similarity index 98% rename from docs/site/manual/vars-backend.md rename to docs/site/manual/manage-root-password-via-vars.md index 9575746e6..5dde4604d 100644 --- a/docs/site/manual/vars-backend.md +++ b/docs/site/manual/manage-root-password-via-vars.md @@ -1,7 +1,4 @@ - -!!! Note - Vars is the new secret backend that will soon replace the Facts backend - +# Managing the root password declaratively using `vars` Defining a linux user's password via the nixos configuration previously required running `mkpasswd ...` and then copying the hash back into the nix configuration. diff --git a/docs/site/manual/migration-guide.md b/docs/site/manual/migration-guide.md index 04b365b70..2c8da831c 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. +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. -!!! 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. +!!! 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. ## Starting Point diff --git a/docs/site/manual/repo-layout.md b/docs/site/manual/repo-layout.md index 56864c95d..5209e75de 100644 --- a/docs/site/manual/repo-layout.md +++ b/docs/site/manual/repo-layout.md @@ -1,3 +1,4 @@ +# Repo Layout Guide This guide will help you navigate the codebase and locate key files: @@ -23,3 +24,37 @@ $ 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), +) +```