diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b54d93993..ab946d538 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: Clan Documentation +site_name: Documentation site_url: https://docs.clan.lol repo_url: https://git.clan.lol/clan/clan-core/ repo_name: "_>" @@ -45,84 +45,95 @@ exclude_docs: | /drafts/ nav: - - Home: index.md + - 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 + - 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: - - 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 - - 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 - - ClanServices: guides/clanServices.md + - Inventory: + - Introduction to Inventory: guides/inventory/inventory.md + - File Autoincludes: guides/inventory/autoincludes.md + + - Clan Services: + - Inventory Guide: guides/inventory/clanServices.md + - Author Your Own Service: guides/services/community.md - Vars: - - Overview: guides/vars/vars-overview.md - - Getting Started: guides/vars/vars-backend.md - - Concepts: guides/vars/vars-concepts.md - - Sops Backend: - - Yubikeys & Age Plugins: guides/vars/sops/age-plugins.md + - Introduction to Vars: guides/vars/vars-overview.md + - Minimal Example: guides/vars/vars-backend.md + - Diving deeper: guides/vars/vars-concepts.md + - Introduction to Vars: guides/vars/vars-overview.md + - Minimal Example: guides/vars/vars-backend.md + - Diving deeper: guides/vars/vars-concepts.md - Advanced Examples: guides/vars/vars-advanced-examples.md - Troubleshooting: guides/vars/vars-troubleshooting.md - - Backup & Restore: guides/backups.md - - Disk Encryption: guides/disk-encryption.md - - Secrets management: guides/secrets.md - - Networking: guides/networking.md - - Zerotier VPN: guides/mesh-vpn.md - - How to disable Secure Boot: guides/secure-boot.md + - Sops Backend: + - Yubikeys & Age Plugins: guides/vars/sops/age-plugins.md + - Managing Users (OLD): guides/secrets.md + - Networking: + - Introduction to Networking: guides/networking/networking.md + - Zerotier VPN: guides/networking/mesh-vpn.md + - Disko Templates: + - Community Disko Templates: guides/disko-templates/community.md + - Backups: + - Introduction to Backups: guides/backups.md - Flake-parts: guides/flake-parts.md - - Nixos-rebuild: guides/nixos-rebuild.md - - macOS: guides/macos.md - - Contributing: - - Contributing: guides/contributing/CONTRIBUTING.md - - Debugging: guides/contributing/debugging.md - - Testing: guides/contributing/testing.md - - - Writing a Service Module: guides/services/community.md - - Writing a Disko Template: guides/disko-templates/community.md - - Nixos-rebuild: guides/nixos-rebuild.md + - NixOs Rebuild: guides/nixos-rebuild.md + - macOS: + - Managing macOS Machines: guides/macos.md + # Should be part of the respective sections above + # machines, disko, clan + # - Templates: concepts/templates.md - Migrations: - - Migrate from clan modules to services: guides/migrations/migrate-inventory-services.md - - Facts Vars Migration: guides/migrations/migration-facts-vars.md + - clan modules --> clan services: guides/migrations/migrate-inventory-services.md + - Facts --> Vars: guides/migrations/migration-facts-vars.md - Disk id: guides/migrations/disk-id.md + - Disk Encryption: guides/disk-encryption.md + - Disable Secure Boot: guides/secure-boot.md + - Contributing: + - Hacking: guides/contributing/CONTRIBUTING.md + - Advanced Debugging: guides/contributing/debugging.md + - Testing: guides/contributing/testing.md - Concepts: - - Inventory: concepts/inventory.md - - Autoincludes: concepts/autoincludes.md - Templates: concepts/templates.md + - Reference: - Overview: reference/index.md - - Browse Options: "/options" - - Services: - - Overview: - - reference/clanServices/index.md - - reference/clanServices/admin.md - - reference/clanServices/borgbackup.md - - reference/clanServices/certificates.md - - reference/clanServices/coredns.md - - reference/clanServices/data-mesher.md - - reference/clanServices/dyndns.md - - reference/clanServices/emergency-access.md - - reference/clanServices/garage.md - - reference/clanServices/hello-world.md - - reference/clanServices/importer.md - - reference/clanServices/localbackup.md - - reference/clanServices/matrix-synapse.md - - reference/clanServices/mycelium.md - - reference/clanServices/monitoring.md - - reference/clanServices/packages.md - - reference/clanServices/sshd.md - - reference/clanServices/syncthing.md - - reference/clanServices/trusted-nix-caches.md - - reference/clanServices/users.md - - reference/clanServices/wifi.md - - reference/clanServices/wireguard.md - - reference/clanServices/zerotier.md - - API: reference/clanServices/clan-service-author-interface.md + - Clan Service API: reference/clanServices/clan-service-author-interface.md + + - clan.core (Machine Options): + - Overview: reference/clan.core/index.md + - reference/clan.core/backups.md + - reference/clan.core/deployment.md + - reference/clan.core/facts.md + - reference/clan.core/networking.md + - reference/clan.core/postgresql.md + - reference/clan.core/settings.md + - reference/clan.core/sops.md + - reference/clan.core/state.md + - reference/clan.core/vars.md + - Clan Service API: reference/clanServices/clan-service-author-interface.md + + - clan.core (Machine Options): + - Overview: reference/clan.core/index.md + - reference/clan.core/backups.md + - reference/clan.core/deployment.md + - reference/clan.core/facts.md + - reference/clan.core/networking.md + - reference/clan.core/postgresql.md + - reference/clan.core/settings.md + - reference/clan.core/sops.md + - reference/clan.core/state.md + - reference/clan.core/vars.md - CLI: - Overview: reference/cli/index.md @@ -141,19 +152,8 @@ nav: - reference/cli/vars.md - reference/cli/vms.md - - clan.core (NixOS Options): - - Overview: reference/clan.core/index.md - - reference/clan.core/backups.md - - reference/clan.core/deployment.md - - reference/clan.core/facts.md - - reference/clan.core/networking.md - - reference/clan.core/postgresql.md - - reference/clan.core/settings.md - - reference/clan.core/sops.md - - reference/clan.core/state.md - - reference/clan.core/vars.md - - - Developer-api: api.md + - HTTP API: api.md + - HTTP API: api.md - Decisions: - Architecture Decisions: decisions/README.md @@ -164,7 +164,34 @@ nav: - 05-deployment-parameters: decisions/05-deployment-parameters.md - Template: decisions/_template.md - Glossary: reference/glossary.md - - Browse Options: "/options" + - Services: + - Introduction to ClanServices: reference/clanServices/index.md + - Official: + - reference/clanServices/admin.md + - reference/clanServices/borgbackup.md + - reference/clanServices/certificates.md + - reference/clanServices/coredns.md + - reference/clanServices/data-mesher.md + - reference/clanServices/dyndns.md + - reference/clanServices/emergency-access.md + - reference/clanServices/garage.md + - reference/clanServices/hello-world.md + - reference/clanServices/importer.md + - reference/clanServices/localbackup.md + - reference/clanServices/matrix-synapse.md + - reference/clanServices/mycelium.md + - reference/clanServices/monitoring.md + - reference/clanServices/packages.md + - reference/clanServices/sshd.md + - reference/clanServices/syncthing.md + - reference/clanServices/trusted-nix-caches.md + - reference/clanServices/users.md + - reference/clanServices/wifi.md + - reference/clanServices/wireguard.md + - reference/clanServices/zerotier.md + - Community: community/services/index.md + + - Clan Options: "/options" docs_dir: site site_dir: out diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py index c5b39dc8a..76c7f09fb 100644 --- a/docs/nix/render_options/__init__.py +++ b/docs/nix/render_options/__init__.py @@ -325,7 +325,7 @@ Each `clanService`: See [Migration Guide](../../guides/migrations/migrate-inventory-services.md) for help on migrating. -Learn how to use `clanServices` in practice in the [Using clanServices guide](../../guides/clanServices.md). +Learn how to use `clanServices` in practice in the [Using clanServices guide](../../guides/inventory/clanServices.md). """ with indexfile.open("w") as of: diff --git a/docs/site/community/services/index.md b/docs/site/community/services/index.md new file mode 100644 index 000000000..58ced0f5f --- /dev/null +++ b/docs/site/community/services/index.md @@ -0,0 +1,27 @@ +Services provided by the community + +!!! tip "Add your own!" + + Have you built a service or a tool for? Open a PR adding a link to this page! + +
+ +- [Your Service Foo](https://example.com) :octicons-link-external-16: + + --- + + Does this and that + +- [Your Service Foo](https://example.com) :octicons-link-external-16: + + --- + + Does this and that + +- [Your Service Foo](https://example.com) :octicons-link-external-16: + + --- + + Does this and that + +
\ No newline at end of file diff --git a/docs/site/guides/disk-encryption.md b/docs/site/guides/disk-encryption.md index f3bc619e7..7fd06e3ea 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](../guides/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](./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 a26d60c5b..a6285cb98 100644 --- a/docs/site/guides/getting-started/add-machines.md +++ b/docs/site/guides/getting-started/add-machines.md @@ -2,11 +2,11 @@ Machines can be added using the following methods -- Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](../../concepts/autoincludes.md)) +- Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](../inventory/autoincludes.md)) - Imperative via cli command: `clan machines create` - Editing nix expressions in flake.nix See [`clan-core.lib.clan`](/options/?scope=Flake Options (clan.nix file)) -See the complete [list](../../concepts/autoincludes.md) of auto-loaded files. +See the complete [list](../inventory/autoincludes.md) of auto-loaded files. ## Create a machine diff --git a/docs/site/guides/getting-started/add-services.md b/docs/site/guides/getting-started/add-services.md index 8c561059c..9d8dcb42f 100644 --- a/docs/site/guides/getting-started/add-services.md +++ b/docs/site/guides/getting-started/add-services.md @@ -10,7 +10,7 @@ In Clan Services are multi-Host & role-based: - You can use tags instead of explicit machine names. -To learn more: [Guide about clanService](../clanServices.md) +To learn more: [Guide about clanService](../inventory/clanServices.md) !!! Important It is recommended to add at least one networking service such as `zerotier` that allows to reach all your clan machines from your setup computer across the globe. @@ -41,7 +41,7 @@ To learn more: [Guide about clanService](../clanServices.md) ``` 1. See [reference/clanServices](../../reference/clanServices/index.md) for all available services and how to configure them. - Or read [authoring/clanServices](../../guides/services/community.md) if you want to bring your own + Or read [authoring/clanServices](../services/community.md) if you want to bring your own 2. Replace `__YOUR_CONTROLLER_` with the *name* of your machine. diff --git a/docs/site/guides/getting-started/convert-flake.md b/docs/site/guides/getting-started/convert-flake.md index 30b0c54ac..ba269bbde 100644 --- a/docs/site/guides/getting-started/convert-flake.md +++ b/docs/site/guides/getting-started/convert-flake.md @@ -171,7 +171,7 @@ Clan needs to know where it can reach your hosts. For testing purpose set } ``` -See our guide on for properly [configuring machines networking](../networking.md) +See our guide on for properly [configuring machines networking](../networking/networking.md) ## Next Steps diff --git a/docs/site/guides/getting-started/create-installer.md b/docs/site/guides/getting-started/create-installer.md index 2476d014b..1f094eb98 100644 --- a/docs/site/guides/getting-started/create-installer.md +++ b/docs/site/guides/getting-started/create-installer.md @@ -152,7 +152,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](../../guides/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](../secure-boot.md) ## (Optional) Connect to Wifi Manually diff --git a/docs/site/guides/getting-started/hardware-report-physical.md b/docs/site/guides/getting-started/hardware-report-physical.md index b0462f8c7..a60a74851 100644 --- a/docs/site/guides/getting-started/hardware-report-physical.md +++ b/docs/site/guides/getting-started/hardware-report-physical.md @@ -3,7 +3,7 @@ Now that you have created a machine, added some services, and set up secrets, this guide will walk you through how to deploy it. -### Step 0. Prerequisites +### 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) @@ -45,7 +45,7 @@ This is an example of the booted installer. │ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion │ │ │ │Multicast DNS: nixos-installer.local │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ │ -│ Press 'Ctrl-C' for console access │ +│ Press 'Ctrl-C' for console access │ │ │ └─────────────────────────────────────────────────────────────────────────────────────┘ ``` @@ -75,12 +75,12 @@ This is an example of the booted installer. There are two ways to deploy your machine: +### Generating a Hardware Report + +The following command will generate a hardware report with [nixos-facter](https://github.com/nix-community/nixos-facter) and writes it back into your machine folder. The `--phases kexec` flag makes sure we are not yet formatting anything, instead if the target system is not a NixOS machine it will use [kexec](https://wiki.archlinux.org/title/Kexec) to switch to a NixOS kernel. === "Password" - ### Generating a Hardware Report - - The following command will generate a hardware report with [nixos-facter](https://github.com/nix-community/nixos-facter) and writes it back into your machine folder. The `--phases kexec` flag makes sure we are not yet formatting anything, instead if the target system is not a NixOS machine it will use [kexec](https://wiki.archlinux.org/title/Kexec) to switch to a NixOS kernel. - + **Password** ```terminal clan machines install [MACHINE] \ @@ -90,11 +90,10 @@ There are two ways to deploy your machine: ``` === "QR Code" - ### Generating a Hardware Report + **QR Code** - The following command will generate a hardware report with [nixos-facter](https://github.com/nix-community/nixos-facter) and writes it back into your machine folder. The `--phases kexec` flag makes sure we are not yet formatting anything, instead if the target system is not a NixOS machine it will use [kexec](https://wiki.archlinux.org/title/Kexec) to switch to a NixOS kernel. + **Using a JSON String or File Path**: - #### Using a JSON String or File Path Copy the JSON string contained in the QR Code and provide its path or paste it directly: ```terminal clan machines install [MACHINE] --json [JSON] \ @@ -102,7 +101,8 @@ There are two ways to deploy your machine: --phases kexec ``` - #### Using an Image Containing the QR Code + **Using an Image Containing the QR Code**: + Provide the path to an image file containing the QR code displayed by the installer: ```terminal clan machines install [MACHINE] --png [PATH] \ @@ -112,3 +112,5 @@ There are two ways to deploy your machine: 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 diff --git a/docs/site/guides/getting-started/update.md b/docs/site/guides/getting-started/update.md index fb15f8261..a88ef7dcf 100644 --- a/docs/site/guides/getting-started/update.md +++ b/docs/site/guides/getting-started/update.md @@ -32,7 +32,7 @@ Ensure that the root login is secured and only used when necessary. ## Multiple Target Hosts -You can now experiment with a new interface that allows you to define multiple `targetHost` addresses for different VPNs. Learn more and try it out in our [networking guide](../networking.md). +You can now experiment with a new interface that allows you to define multiple `targetHost` addresses for different VPNs. Learn more and try it out in our [networking guide](../networking/networking.md). ## Updating Machine Configurations diff --git a/docs/site/concepts/autoincludes.md b/docs/site/guides/inventory/autoincludes.md similarity index 100% rename from docs/site/concepts/autoincludes.md rename to docs/site/guides/inventory/autoincludes.md diff --git a/docs/site/guides/clanServices.md b/docs/site/guides/inventory/clanServices.md similarity index 93% rename from docs/site/guides/clanServices.md rename to docs/site/guides/inventory/clanServices.md index 2dae408ae..cd590a33f 100644 --- a/docs/site/guides/clanServices.md +++ b/docs/site/guides/inventory/clanServices.md @@ -1,5 +1,3 @@ -# Using the Inventory - Clan's inventory system is a composable way to define and deploy services across machines. @@ -70,7 +68,7 @@ inventory.instances = { ## Module Settings Each role might expose configurable options. See clan's [clanServices -reference](../reference/clanServices/index.md) for all available options. +reference](../../reference/clanServices/index.md) for all available options. Settings can be set in per-machine or per-role. The latter is applied to all machines that are assigned to that role. @@ -157,13 +155,13 @@ inventory.instances = { You can use services exposed by Clan's core module library, `clan-core`. -🔗 See: [List of Available Services in clan-core](../reference/clanServices/index.md) +🔗 See: [List of Available Services in clan-core](../../reference/clanServices/index.md) ## Defining Your Own Service You can also author your own `clanService` modules. -🔗 Learn how to write your own service: [Authoring a service](../guides/services/community.md) +🔗 Learn how to write your own service: [Authoring a service](../services/community.md) You might expose your service module from your flake — this makes it easy for other people to also use your module in their clan. @@ -179,7 +177,7 @@ ______________________________________________________________________ ## What's Next? -- [Author your own clanService →](../guides/services/community.md) -- [Migrate from clanModules →](../guides/migrations/migrate-inventory-services.md) +- [Author your own clanService →](../services/community.md) +- [Migrate from clanModules →](../migrations/migrate-inventory-services.md) diff --git a/docs/site/concepts/inventory.md b/docs/site/guides/inventory/inventory.md similarity index 96% rename from docs/site/concepts/inventory.md rename to docs/site/guides/inventory/inventory.md index 71db8b235..4659849f2 100644 --- a/docs/site/concepts/inventory.md +++ b/docs/site/guides/inventory/inventory.md @@ -17,13 +17,13 @@ The following tutorial will walk through setting up a Backup service where the t ## Prerequisites -- [x] [Add some machines](../guides/getting-started/add-machines.md) to your Clan. +- [x] [Add some machines](../getting-started/add-machines.md) to your Clan. ## Services The inventory defines `instances` of clan services. Membership of `machines` is defined via `roles` exclusively. -See each [modules documentation](../reference/clanServices/index.md) for its available roles. +See each [modules documentation](../../reference/clanServices/index.md) for its available roles. ### Adding services to machines diff --git a/docs/site/guides/macos.md b/docs/site/guides/macos.md index 8ab609e5a..8b388fd10 100644 --- a/docs/site/guides/macos.md +++ b/docs/site/guides/macos.md @@ -7,7 +7,7 @@ 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/vars-overview.md) +- Support for [vars](./vars/vars-overview.md) ## Add Your Machine to Your Clan Flake diff --git a/docs/site/guides/migrations/migrate-inventory-services.md b/docs/site/guides/migrations/migrate-inventory-services.md index 4f64d5655..8c2c89059 100644 --- a/docs/site/guides/migrations/migrate-inventory-services.md +++ b/docs/site/guides/migrations/migrate-inventory-services.md @@ -1,7 +1,7 @@ # Migrating from using `clanModules` to `clanServices` **Audience**: This is a guide for **people using `clanModules`**. -If you are a **module author** and need to migrate your modules please consult our **new** [clanServices authoring guide](../../guides/services/community.md) +If you are a **module author** and need to migrate your modules please consult our **new** [clanServices authoring guide](../services/community.md) ## What's Changing? @@ -378,6 +378,6 @@ instances = { ## Further reference -* [Inventory Concept](../../concepts/inventory.md) -* [Authoring a 'clan.service' module](../../guides/services/community.md) -* [ClanServices](../clanServices.md) +* [Inventory Concept](../inventory/inventory.md) +* [Authoring a 'clan.service' module](../services/community.md) +* [ClanServices](../inventory/clanServices.md) diff --git a/docs/site/guides/migrations/migration-facts-vars.md b/docs/site/guides/migrations/migration-facts-vars.md index f9c3323aa..8f06ed38d 100644 --- a/docs/site/guides/migrations/migration-facts-vars.md +++ b/docs/site/guides/migrations/migration-facts-vars.md @@ -2,8 +2,8 @@ For a high level overview about `vars` see our [blog post](https://clan.lol/blog/vars/). -This guide will help you migrate your modules that still use our [`facts`](../../guides/secrets.md) backend -to the [`vars`](../../guides/vars/vars-overview.md) backend. +This guide will help you migrate your modules that still use our [`facts`](../secrets.md) backend +to the [`vars`](../vars/vars-overview.md) backend. The `vars` [module](../../reference/clan.core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync. diff --git a/docs/site/guides/mesh-vpn.md b/docs/site/guides/networking/mesh-vpn.md similarity index 100% rename from docs/site/guides/mesh-vpn.md rename to docs/site/guides/networking/mesh-vpn.md diff --git a/docs/site/guides/networking.md b/docs/site/guides/networking/networking.md similarity index 100% rename from docs/site/guides/networking.md rename to docs/site/guides/networking/networking.md diff --git a/docs/site/guides/secrets.md b/docs/site/guides/secrets.md index 5d027de34..14652e52e 100644 --- a/docs/site/guides/secrets.md +++ b/docs/site/guides/secrets.md @@ -1,5 +1,5 @@ -This article provides an overview over the underlying secrets system which is used by [Vars](../guides/vars/vars-overview.md). -Under most circumstances you should use [Vars](../guides/vars/vars-overview.md) directly instead. +This article provides an overview over the underlying secrets system which is used by [Vars](./vars/vars-overview.md). +Under most circumstances you should use [Vars](./vars/vars-overview.md) directly instead. Consider using `clan secrets` only for managing admin users and groups, as well as a debugging tool. diff --git a/docs/site/guides/services/community.md b/docs/site/guides/services/community.md index 3ff012e96..ba2687feb 100644 --- a/docs/site/guides/services/community.md +++ b/docs/site/guides/services/community.md @@ -301,5 +301,5 @@ instnaces.machine-type = { ## Further Reading - [Reference Documentation for Service Authors](../../reference/clanServices/clan-service-author-interface.md) -- [Migration Guide from ClanModules to ClanServices](../../guides/migrations/migrate-inventory-services.md) +- [Migration Guide from ClanModules to ClanServices](../migrations/migrate-inventory-services.md) - [Decision that lead to ClanServices](../../decisions/01-ClanModules.md) diff --git a/docs/site/guides/vars/vars-overview.md b/docs/site/guides/vars/vars-overview.md index 0048ac7eb..8fd33edea 100644 --- a/docs/site/guides/vars/vars-overview.md +++ b/docs/site/guides/vars/vars-overview.md @@ -1,4 +1,3 @@ -# Vars System Overview The vars system is clan's declarative solution for managing generated files, secrets, and dynamic configuration in your NixOS deployments. It eliminates the manual steps of generating credentials, certificates, and other dynamic values by automating these processes within your infrastructure-as-code workflow. @@ -19,7 +18,7 @@ This approach has several problems: - **Not reproducible**: Manual steps vary between team members -- **Hard to maintain**: Updating secrets requires remembering manual commands +- **Hard to maintain**: Updating secrets requires remembering manual commands - **Deployment friction**: Secrets must be managed outside of your configuration @@ -38,7 +37,7 @@ clan.core.vars.generators.root-password = { runtimeInputs = [ pkgs.mkpasswd ]; }; -users.users.root.hashedPasswordFile = +users.users.root.hashedPasswordFile = config.clan.core.vars.generators.root-password.files.hash.path; ``` @@ -92,7 +91,7 @@ Define how to create files from inputs: - **Prompts**: Values requested from users -- **Scripts**: Generation logic +- **Scripts**: Generation logic - **Dependencies**: Other generators this depends on @@ -123,9 +122,9 @@ Here's a complete example showing password generation and usage: ''; runtimeInputs = [ pkgs.mkpasswd ]; }; - + users.users.myuser = { - hashedPasswordFile = + hashedPasswordFile = config.clan.core.vars.generators.user-password.files.hash.path; }; } diff --git a/docs/site/index.md b/docs/site/index.md index d9d391532..318b0f997 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -1,39 +1,107 @@ --- hide: - - navigation - toc --- -# :material-home: What is Clan? +# What is Clan? + -## :material-book: Guides +
+ +
+

Clan is a peer-to-peer computer management framework that empowers you to selfhost in a reliable and scalable way.

+

Built on NixOS, Clan provides a declarative interface for managing machines with automated secret management, easy mesh VPN connectivity, and automated backups.

+

Whether you're running a homelab or maintaining critical computing infrastructure, Clan will help reduce maintenance burden by allowing a git repository to define your whole network of computers.

+

In combination with sops-nix, nixos-anywhere and disko, Clan makes it possible to have collaborative infrastructure.

+

At the heart of Clan are Clan Services - the core concept that enables you to add functionality across multiple machines in your network. While Clan ships with essential core services, you can create custom services tailored to your specific needs.

+
+ +
-How-to Guides for achieving a certain goal or solving a specific issue. +--- + +[Get started](./guides/getting-started/index.md){ .md-button .md-button--primary } +[View on Gitea](https://git.clan.lol/clan/clan-core){ .md-button } + +## Guides
-- [:material-clock-fast: Getting Started](./guides/getting-started/index.md) +- [Inventory](./guides/inventory/inventory.md) --- - Get started in less than 20 minutes! + Learn how about inventory + +- [Vars](./guides/vars/vars-overview.md) + + --- + + Learn how to use vars - [macOS](./guides/macos.md) @@ -41,35 +109,40 @@ How-to Guides for achieving a certain goal or solving a specific issue. Using Clan to manage your macOS machines -- [Contribute](./guides/contributing/CONTRIBUTING.md) - - --- - - How to set up a development environment -
-## Concepts - -Explore the underlying principles of Clan +## Reference
-- [Vars](./guides/vars/vars-overview.md) +- [CLI](./reference/cli/index.md) --- - Learn about Generators, our way to secret management + command line interface -- [Inventory](./concepts/inventory.md) +- [Clan Options](/options) --- - Learn about the Inventory, a multi machine Nix interface + Search all options + +- [Services](./reference/clanServices/index.md) + + --- + + Discover services
- ## Blog -Visit our [Clan Blog](https://clan.lol/blog/) for the latest updates, tutorials, and community stories. +
+ +- [Clan Blog](https://clan.lol/blog/) + + --- + + For the latest updates, tutorials, and community stories. + +