docs: move getting-started out of guides
This commit is contained in:
Johannes Kirschbauer
@@ -47,18 +47,18 @@ exclude_docs: |
|
||||
nav:
|
||||
- Getting Started:
|
||||
- Overview: index.md
|
||||
- guides/getting-started/creating-your-first-clan.md
|
||||
- guides/getting-started/add-machines.md
|
||||
- guides/getting-started/add-users.md
|
||||
- guides/getting-started/add-services.md
|
||||
- getting-started/creating-your-first-clan.md
|
||||
- getting-started/add-machines.md
|
||||
- getting-started/add-users.md
|
||||
- getting-started/add-services.md
|
||||
- Deploy to Physical Machine:
|
||||
- guides/getting-started/deploy-to-physical-machine/flash-installer.md
|
||||
- guides/getting-started/deploy-to-physical-machine/install-machine.md
|
||||
- guides/getting-started/deploy-to-virtual-machine.md
|
||||
- guides/getting-started/configure-disk.md
|
||||
- guides/getting-started/update-machines.md
|
||||
- guides/getting-started/continuous-integration.md
|
||||
- guides/getting-started/convert-existing-NixOS-configuration.md
|
||||
- getting-started/deploy-to-physical-machine/flash-installer.md
|
||||
- getting-started/deploy-to-physical-machine/install-machine.md
|
||||
- getting-started/deploy-to-virtual-machine.md
|
||||
- getting-started/configure-disk.md
|
||||
- getting-started/update-machines.md
|
||||
- getting-started/continuous-integration.md
|
||||
- getting-started/convert-existing-NixOS-configuration.md
|
||||
- Guides:
|
||||
- Inventory:
|
||||
- Introduction to Inventory: guides/inventory/inventory.md
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
Machines can be added using the following methods
|
||||
|
||||
- Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](../inventory/autoincludes.md))
|
||||
- Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](/guides/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](../inventory/autoincludes.md) of auto-loaded files.
|
||||
See the complete [list](/guides/inventory/autoincludes.md) of auto-loaded files.
|
||||
|
||||
## Create a machine
|
||||
|
||||
@@ -18,8 +18,6 @@ See the complete [list](../inventory/autoincludes.md) of auto-loaded files.
|
||||
};
|
||||
|
||||
# Additional NixOS configuration can be added here.
|
||||
# machines/jon/configuration.nix will be automatically imported.
|
||||
# See: https://docs.clan.lol/guides/more-machines/#automatic-registration
|
||||
machines = {
|
||||
# jon = { config, ... }: {
|
||||
# environment.systemPackages = [ pkgs.asciinema ];
|
||||
@@ -8,7 +8,7 @@ In Clan Services are multi-Host & role-based:
|
||||
|
||||
- You can use tags instead of explicit machine names.
|
||||
|
||||
To learn more: [Guide about clanService](../inventory/clanServices.md)
|
||||
To learn more: [Guide about clanService](/guides/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.
|
||||
@@ -38,8 +38,8 @@ To learn more: [Guide about clanService](../inventory/clanServices.md)
|
||||
}
|
||||
```
|
||||
|
||||
1. See [reference/clanServices](../../reference/clanServices/index.md) for all available services and how to configure them.
|
||||
Or read [authoring/clanServices](../services/community.md) if you want to bring your own
|
||||
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
|
||||
|
||||
2. Replace `__YOUR_CONTROLLER_` with the *name* of your machine.
|
||||
|
||||
@@ -71,5 +71,5 @@ Adding the following services is recommended for most users:
|
||||
```
|
||||
|
||||
1. The `admin` service will generate a **root-password** and **add your ssh-key** that allows for convienient administration.
|
||||
2. Equivalent to directly setting `authorizedKeys` like in [configuring a machine](./add-machines.md#configuring-a-machine)
|
||||
2. Equivalent to directly setting `authorizedKeys` like in [configuring a machine](/getting-started/add-machines.md#configuring-a-machine)
|
||||
3. Adds `user = jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment.
|
||||
@@ -3,15 +3,15 @@
|
||||
The users concept of clan is not done yet. This guide outlines some solutions from our community.
|
||||
Defining users can be done in many different ways. We want to highlight two approaches:
|
||||
|
||||
- Using clan's [users](../../reference/clanServices/users.md) service.
|
||||
- Using clan's [users](/reference/clanServices/users.md) service.
|
||||
- Using a custom approach.
|
||||
|
||||
## Adding Users using the [users](../../reference/clanServices/users.md) service
|
||||
## Adding Users using the [users](/reference/clanServices/users.md) service
|
||||
|
||||
To add a first *user* this guide will be leveraging two things:
|
||||
|
||||
- [clanServices](../../reference/clanServices/index.md): Allows to bind arbitrary logic to something we call an `ìnstance`.
|
||||
- [clanServices/users](../../reference/clanServices/users.md): Implements logic for adding a single user perInstance.
|
||||
- [clanServices](/reference/clanServices/index.md): Allows to bind arbitrary logic to something we call an `ìnstance`.
|
||||
- [clanServices/users](/reference/clanServices/users.md): Implements logic for adding a single user perInstance.
|
||||
|
||||
The example shows how to add a user called `jon`:
|
||||
|
||||
@@ -49,7 +49,7 @@ The example shows how to add a user called `jon`:
|
||||
|
||||
The `users` service creates a `/home/jon` directory, allows `jon` to sign in and will take care of the user's password.
|
||||
|
||||
For more information see [clanService/users](../../reference/clanServices/users.md)
|
||||
For more information see [clanService/users](/reference/clanServices/users.md)
|
||||
|
||||
## Using a custom approach
|
||||
|
||||
@@ -2,7 +2,7 @@ This guide will help you convert your existing NixOS configurations into a Clan.
|
||||
|
||||
!!! Warning
|
||||
Migrating instead of starting new can be trickier and might lead to bugs or
|
||||
unexpected issues. We recommend reading the [Getting Started](/guides/getting-started/creating-your-first-clan.md) guide first.
|
||||
unexpected issues. We recommend reading the [Getting Started](/getting-started/creating-your-first-clan.md) guide first.
|
||||
|
||||
Once you have a working setup and understand the concepts transfering your NixOS configurations over is easy.
|
||||
|
||||
@@ -169,7 +169,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/networking.md)
|
||||
See our guide on for properly [configuring machines networking](/guides/networking/networking.md)
|
||||
|
||||
## Next Steps
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
To install Clan on physical machines, you need to use our custom installer image. This is necessary for proper installation and operation.
|
||||
|
||||
!!! note "Deploying to a Virtual Machine?"
|
||||
If you're deploying to a virtual machine (VM), you can skip this section and go directly to the [Deploy Virtual Machine](/guides/getting-started/deploy-to-virtual-machine.md) step. In this scenario, we automatically use [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to replace the kernel during runtime.
|
||||
If you're deploying to a virtual machine (VM), you can skip this section and go directly to the [Deploy Virtual Machine](/getting-started/deploy-to-virtual-machine.md) step. In this scenario, we automatically use [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to replace the kernel during runtime.
|
||||
|
||||
??? info "Why nixos-anywhere Doesn't Work on Physical Hardware?"
|
||||
nixos-anywhere relies on [kexec](https://wiki.archlinux.org/title/Kexec) to replace the running kernel with our custom one. This method often has compatibility issues with real hardware, especially systems with dedicated graphics cards like laptops and servers, leading to crashes and black screens.
|
||||
@@ -4,13 +4,13 @@ Now that you have created a machine, added some services, and set up secrets, th
|
||||
### 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](/guides/getting-started/add-machines.md)
|
||||
- [x] **Machine configuration**: See our basic [adding and configuring machine guide](/getting-started/add-machines.md)
|
||||
- [x] **Initialized secrets**: See [secrets](/guides/secrets.md) for how to initialize your secrets.
|
||||
- [x] **USB Flash Drive**: See [Clan Installer](/guides/getting-started/flash-installer.md)
|
||||
- [x] **USB Flash Drive**: See [Clan Installer](/getting-started/flash-installer.md)
|
||||
|
||||
|
||||
### Image Installer
|
||||
This method makes use of the [image installers](/guides/getting-started/flash-installer.md).
|
||||
This method makes use of the [image installers](/getting-started/flash-installer.md).
|
||||
|
||||
The installer will randomly generate a password and local addresses on boot, then run a SSH server with these preconfigured.
|
||||
The installer shows its deployment relevant information in two formats, a text form, as well as a QR code.
|
||||
@@ -66,7 +66,7 @@ This is an example of the booted installer.
|
||||
```
|
||||
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](/guides/getting-started/flash-installer.md).
|
||||
3. See how to connect the installer medium to wlan [here](/getting-started/flash-installer.md).
|
||||
|
||||
!!!tip
|
||||
For easy sharing of deployment information via QR code, we highly recommend using [KDE Connect](https://apps.kde.org/de/kdeconnect/).
|
||||
@@ -111,4 +111,4 @@ The following command will generate a hardware report with [nixos-facter](https:
|
||||
|
||||
If you are using our template `[MACHINE]` would be `jon`
|
||||
|
||||
[Next Step (Choose Disk Format)](/guides/getting-started/configure-disk.md){ .md-button .md-button--primary }
|
||||
[Next Step (Choose Disk Format)](/getting-started/configure-disk.md){ .md-button .md-button--primary }
|
||||
@@ -31,7 +31,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/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](/guides/networking/networking.md).
|
||||
|
||||
## Updating Machine Configurations
|
||||
|
||||
@@ -78,7 +78,7 @@ clan {
|
||||
|
||||
`buildHost` / `targetHost`, and other network settings can be temporarily overridden for a single command:
|
||||
|
||||
For the full list of flags refer to the [Clan CLI](../../reference/cli/index.md)
|
||||
For the full list of flags refer to the [Clan CLI](/reference/cli/index.md)
|
||||
|
||||
```bash
|
||||
# Build on a remote host
|
||||
@@ -17,13 +17,13 @@ The following tutorial will walk through setting up a Backup service where the t
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [x] [Add some machines](../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
|
||||
|
||||
|
||||
@@ -64,5 +64,5 @@ nixos-rebuild switch --flake .#my-machine --target-host root@target-ip --build-h
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Update Your Machines](/guides/getting-started/update-machine.md) - Using clan's update command
|
||||
- [Update Your Machines](/getting-started/update-machine.md) - Using clan's update command
|
||||
- [Variables (Vars)](/guides/vars/vars-overview.md) - Understanding the vars system
|
||||
|
||||
@@ -85,7 +85,7 @@ hide:
|
||||
|
||||
---
|
||||
|
||||
[Get started](/guides/getting-started/creating-your-first-clan){ .md-button .md-button--primary }
|
||||
[Get started](/getting-started/creating-your-first-clan.md){ .md-button .md-button--primary }
|
||||
[View on Gitea](https://git.clan.lol/clan/clan-core){ .md-button }
|
||||
|
||||
## Guides
|
||||
|
||||
Reference in New Issue
Block a user