Reapply "docs: Document imports dir. Remove What's next sections everywhere. Merge guide overview and hompage view."
This reverts commit b19beb8913.
This commit is contained in:
Qubasa
@@ -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(
|
||||
["<path_to_local_src>#nixos-anywhere"],
|
||||
cmd,
|
||||
),
|
||||
RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True),
|
||||
)
|
||||
```
|
||||
|
||||
# Standards
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
---
|
||||
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
@@ -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
|
||||
|
||||
---
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
# Mesh VPN
|
||||
|
||||
This guide provides detailed instructions for configuring
|
||||
[ZeroTier VPN](https://zerotier.com) within Clan. Follow the
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.**
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
@@ -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: Authoring clanModules](./clanmodules/index.md)
|
||||
|
||||
</div>
|
||||
|
||||
## :material-book: Guides
|
||||
|
||||
**How-to Guides for achieving a certain goal or solving a specific issue.**
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- [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!
|
||||
|
||||
</div>
|
||||
|
||||
## API Reference
|
||||
|
||||
**Auto generated API Documentation**
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- [Reference Overview](./reference/index.md)
|
||||
|
||||
---
|
||||
|
||||
Learn how to interface with Clan programmatically
|
||||
|
||||
[: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)
|
||||
|
||||
</div>
|
||||
@@ -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 `<CLAN_ROOT>/imports` exists within the Clan. Below are the conditions for importing inventory modules:
|
||||
|
||||
- **Inventory Modules**: Modules located in `<CLAN_ROOT>/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 `<CLAN_ROOT>/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).
|
||||
|
||||
@@ -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!
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
# Disk Templates
|
||||
|
||||
|
||||
!!! Danger ":fontawesome-solid-road-barrier: Under Construction :fontawesome-solid-road-barrier:"
|
||||
Currently under construction use with caution
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.**
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :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)
|
||||
|
||||
</div>
|
||||
|
||||
## Guides
|
||||
|
||||
**How-to Guides for achieving a certain goal or solving a specific issue.**
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- [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!
|
||||
|
||||
</div>
|
||||
@@ -1,4 +1,3 @@
|
||||
# Inventory
|
||||
|
||||
`Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries.
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# 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!**
|
||||
!!! 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
|
||||
|
||||
@@ -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(
|
||||
["<path_to_local_src>#nixos-anywhere"],
|
||||
cmd,
|
||||
),
|
||||
RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True),
|
||||
)
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user