docs: decompose configuration guide
This commit is contained in:
parent
d2b7bd593b
commit
3a9c84cb45
|
|
@ -32,6 +32,7 @@ exclude_docs: |
|
|||
nav:
|
||||
- Getting started:
|
||||
- index.md
|
||||
- Configure: getting-started/configure.md
|
||||
- Deploy Machine: getting-started/machines.md
|
||||
- Installer: getting-started/installer.md
|
||||
- Setup Networking: getting-started/networking.md
|
||||
|
|
|
|||
96
docs/site/getting-started/configure.md
Normal file
96
docs/site/getting-started/configure.md
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
# Configuration - How to configure clan with your own machines
|
||||
|
||||
## Global configuration
|
||||
|
||||
In the `flake.nix` file:
|
||||
|
||||
- [x] set a unique `clanName`.
|
||||
- [ ] set `clanIcon` (optional)
|
||||
- [ ] Set `machineIcon` per machine (optional)
|
||||
|
||||
These icons will be used by our future GUI.
|
||||
|
||||
```nix title="clan-core.lib.buildClan"
|
||||
buildClan {
|
||||
# Set a unique name
|
||||
clanName = "Lobsters";
|
||||
# Optional, a path to an image file
|
||||
clanIcon = ./path/to/file;
|
||||
|
||||
machines = {
|
||||
jon = {
|
||||
# ...
|
||||
# Optional, a path to an image file
|
||||
clanCore.machineIcon = ./path/to/file;
|
||||
};
|
||||
# ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Machine configuration guide
|
||||
|
||||
To add or configure a new machine in clan we provide these simple steps:
|
||||
|
||||
### Step 1. Identify Target Disk-ID
|
||||
|
||||
1. Find the remote disk id by executing:
|
||||
|
||||
```bash title="setup computer"
|
||||
ssh root@<target-computer> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
|
||||
```
|
||||
|
||||
Which should show something like:
|
||||
|
||||
```bash
|
||||
NAME ID-LINK FSTYPE SIZE MOUNTPOINT
|
||||
sda usb-ST_16GB_AA6271026J1000000509-0:0 14.9G
|
||||
├─sda1 usb-ST_16GB_AA6271026J1000000509-0:0-part1 1M
|
||||
├─sda2 usb-ST_16GB_AA6271026J1000000509-0:0-part2 vfat 100M /boot
|
||||
└─sda3 usb-ST_16GB_AA6271026J1000000509-0:0-part3 ext4 2.9G /
|
||||
nvme0n1 nvme-eui.e8238fa6bf530001001b448b4aec2929 476.9G
|
||||
├─nvme0n1p1 nvme-eui.e8238fa6bf530001001b448b4aec2929-part1 vfat 512M
|
||||
├─nvme0n1p2 nvme-eui.e8238fa6bf530001001b448b4aec2929-part2 ext4 459.6G
|
||||
└─nvme0n1p3 nvme-eui.e8238fa6bf530001001b448b4aec2929-part3 swap 16.8G
|
||||
```
|
||||
|
||||
2. Edit the following fields inside the `flake.nix`
|
||||
|
||||
```nix title="clan-core.lib.buildClan"
|
||||
buildClan {
|
||||
# ...
|
||||
machines = {
|
||||
"jon" = {
|
||||
# ...
|
||||
|
||||
# Change this to the correct ip-address or hostname
|
||||
# The hostname is the machine name by default
|
||||
clan.networking.targetHost = pkgs.lib.mkDefault "root@<hostname>"
|
||||
|
||||
# Change this to the ID-LINK of the desired disk shown by 'lsblk'
|
||||
clan.diskLayouts.singleDiskExt4 = {
|
||||
device = "/dev/disk/by-id/__CHANGE_ME__";
|
||||
}
|
||||
|
||||
# ...
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Step 2. Detect hardware specific drivers
|
||||
|
||||
1. Generate a `hardware-configuration.nix` for your target computer
|
||||
|
||||
```bash
|
||||
ssh root@<target-computer> nixos-generate-config --no-filesystems --show-hardware-config > hardware-configuration.nix
|
||||
```
|
||||
|
||||
2. Move the generated file into `machines/jon/hardware-configuration.nix` folder.
|
||||
|
||||
## Step 3. Initialize the facts
|
||||
|
||||
!!! Info
|
||||
**All facts are automatically initialized.**
|
||||
|
||||
If you need additional help see our [facts chapter](./secrets.md)
|
||||
|
|
@ -84,7 +84,8 @@ For connecting via Wifi, please consult the guide below.
|
|||
|
||||
### Whats next?
|
||||
|
||||
- [Deploying Machines](machines.md): Deploying a Machine configuration
|
||||
- [Configure Machines](configure.md): Customise machine configuration
|
||||
- [Deploying](machines.md): Deploying a Machine configuration
|
||||
- [WiFi](#optional-connect-to-wifi): Guide for connecting to Wifi.
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -12,10 +12,13 @@ This process involves preparing a suitable hardware and disk partitioning config
|
|||
|
||||
### Step 0. Prerequisites
|
||||
|
||||
- [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.
|
||||
|
||||
=== "**Physical Hardware**"
|
||||
|
||||
- [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 [configuration guide](./configure.md)
|
||||
- [x] **Initialized secrets**: See [secrets](secrets.md) for how to initialize your secrets.
|
||||
- [x] **USB Flash Drive**: See [Clan Installer](installer.md)
|
||||
|
||||
!!! Steps
|
||||
|
||||
1. Create a NixOS installer image and transfer it to a bootable USB drive as described in the [installer](./installer.md).
|
||||
|
|
@ -24,9 +27,13 @@ This process involves preparing a suitable hardware and disk partitioning config
|
|||
|
||||
=== "**Cloud Machines**"
|
||||
|
||||
- [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 [configuration guide](./configure.md)
|
||||
- [x] **Initialized secrets**: See [secrets](secrets.md) for how to initialize your secrets.
|
||||
|
||||
!!! Steps
|
||||
|
||||
- Use any linux machine if it is reachable via SSH and supports `kexec`.
|
||||
- Any cloud machine if it is reachable via SSH and supports `kexec`.
|
||||
|
||||
Confirm the machine is reachable via SSH from your setup computer.
|
||||
|
||||
|
|
@ -34,77 +41,11 @@ Confirm the machine is reachable via SSH from your setup computer.
|
|||
ssh root@<your_target_machine_ip>
|
||||
```
|
||||
|
||||
- [x] **Machine configuration**: You want to deploy. [Check out our templates](../templates/index.md)
|
||||
- [x] Initialized secrets: See [secrets](secrets.md) for how to initialize your secrets.
|
||||
- [x] (Optional) USB Flash Drive with the [Clan Installer](installer.md)
|
||||
|
||||
### Step 1. Identify Target Disk-ID
|
||||
|
||||
Run the following command:
|
||||
```bash
|
||||
lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
|
||||
```
|
||||
It should show something like:
|
||||
```bash
|
||||
NAME ID-LINK FSTYPE SIZE MOUNTPOINT
|
||||
sda usb-ST_16GB_AA6271026J1000000509-0:0 14.9G
|
||||
├─sda1 usb-ST_16GB_AA6271026J1000000509-0:0-part1 1M
|
||||
├─sda2 usb-ST_16GB_AA6271026J1000000509-0:0-part2 vfat 100M /boot
|
||||
└─sda3 usb-ST_16GB_AA6271026J1000000509-0:0-part3 ext4 2.9G /
|
||||
nvme0n1 nvme-eui.e8238fa6bf530001001b448b4aec2929 476.9G
|
||||
├─nvme0n1p1 nvme-eui.e8238fa6bf530001001b448b4aec2929-part1 vfat 512M
|
||||
├─nvme0n1p2 nvme-eui.e8238fa6bf530001001b448b4aec2929-part2 ext4 459.6G
|
||||
└─nvme0n1p3 nvme-eui.e8238fa6bf530001001b448b4aec2929-part3 swap 16.8G
|
||||
```
|
||||
|
||||
Now change the following lines of your configuration you want to deploy.
|
||||
We need to set the hardware specific `disk-id` (i.e. `nvme-eui.e8238fa6bf530001001b448b4aec2929`)
|
||||
|
||||
Import the clan `diskLayouts` Module.
|
||||
```
|
||||
imports = [
|
||||
clan-core.clanModules.diskLayouts
|
||||
]
|
||||
```
|
||||
|
||||
```nix
|
||||
# flake.nix / configuration.nix
|
||||
clan.diskLayouts.singleDiskExt4 = {
|
||||
device = "/dev/disk/by-id/<MY_DISK_ID>";
|
||||
}
|
||||
```
|
||||
|
||||
Also set the targetHost: (i.e. user `root` hostname `jon`)
|
||||
The hostname is the **machine name** by default
|
||||
|
||||
```nix
|
||||
clan.networking.targetHost = pkgs.lib.mkDefault "root@jon"
|
||||
```
|
||||
|
||||
`cd` into your `my-clan` directory
|
||||
|
||||
```bash
|
||||
my-clan (main)> tree
|
||||
.
|
||||
├── flake.lock
|
||||
├── flake.nix
|
||||
└── machines
|
||||
└── jon
|
||||
└── configuration.nix
|
||||
```
|
||||
|
||||
And verify that the machine configuration is detected from the `clan` cli.
|
||||
|
||||
```bash
|
||||
clan machines list
|
||||
#> jon
|
||||
```
|
||||
|
||||
### Step 3. Deploy the machine
|
||||
### Step 1. Deploy the machine
|
||||
|
||||
**Finally deployment time!** Use the following command to build and deploy the image via SSH onto your machine.
|
||||
|
||||
Replace `<target_host>` with the **installer's ip address**:
|
||||
Replace `<target_host>` with the **target computers' ip address**:
|
||||
|
||||
```bash
|
||||
clan machines install my-machine <target_host>
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Secrets
|
||||
# Secrets / Facts
|
||||
|
||||
Clan enables encryption of secrets (such as passwords & keys) ensuring security and ease-of-use among users.
|
||||
|
||||
|
|
|
|||
|
|
@ -84,6 +84,15 @@ This should yield the following:
|
|||
5 directories, 6 files
|
||||
```
|
||||
|
||||
```bash
|
||||
clan machines list
|
||||
```
|
||||
|
||||
```bash
|
||||
jon
|
||||
sara
|
||||
```
|
||||
|
||||
!!! success
|
||||
|
||||
You just successfully bootstrapped your first clan directory.
|
||||
|
|
@ -92,51 +101,12 @@ This should yield the following:
|
|||
|
||||
### What's Next?
|
||||
|
||||
- [**Deploy Machines**](./getting-started/machines.md): Learn how to deploy to any remote machine.
|
||||
- **Machine Configuration**: Declare behavior and configuration of machines.
|
||||
|
||||
---
|
||||
|
||||
### Edit Flake.nix
|
||||
|
||||
Open the `flake.nix` file and set a unique `clanName` if you want you can also set an optional `clanIcon` or even a per `machineIcon`. These will be used by our future clan GUI.
|
||||
|
||||
### Remote into the target machine
|
||||
|
||||
**Right now clan assumes that you already have NixOS running on the target machine.**
|
||||
|
||||
If that is not the case you can use our [installer image](getting-started/installer.md) that automatically generates an endpoint reachable over TOR with a random ssh password.
|
||||
|
||||
On the remote execute:
|
||||
1. Generate a hardware-config.nix
|
||||
```bash
|
||||
nixos-generate-config --root /etc/nixos --no-filesystems
|
||||
```
|
||||
2. Copy it over and put it into you `machines/jon/hardware-config.nix` folder
|
||||
```bash
|
||||
scp -r root@<jon-ip>:/etc/nixos/hardware-config.nix ./machines/jon
|
||||
```
|
||||
3. Find the remote disk id by executing on the remote:
|
||||
```bash
|
||||
lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
|
||||
```
|
||||
4. Edit the following fields inside the `flake.nix`
|
||||
- `clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";`
|
||||
- `clan.diskLayouts.singleDiskExt4 = {
|
||||
device = "/dev/disk/by-id/__CHANGE_ME__";
|
||||
};`
|
||||
|
||||
5. Generate secrets used by clan modules by executing
|
||||
```bash
|
||||
clan facts generate
|
||||
```
|
||||
|
||||
### **Next Steps**
|
||||
Ready to expand? Explore how to install a new machine with the helpful documentation [here](getting-started/machines.md).
|
||||
Ready to explore more?
|
||||
|
||||
- **Adding New Machines to your setup**. [Follow our templates](templates/index.md)
|
||||
|
||||
- **Use a USB drive to Set Up Machines**: Setting up new computers remotely is easy with an USB stick. [Learn how](getting-started/machines.md).
|
||||
- [**Machine Configuration**](getting-started/configure.md): Declare behavior and configuration of machines.
|
||||
|
||||
- [**Deploy Machines**](getting-started/machines.md): Learn how to deploy to any remote machine.
|
||||
|
||||
- [**Installer**](getting-started/installer.md): Setting up new computers remotely is easy with an USB stick.
|
||||
|
||||
- [**Check out out Templates**](templates/index.md)
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,174 +0,0 @@
|
|||
{
|
||||
"nodes": {
|
||||
"clan-core": {
|
||||
"inputs": {
|
||||
"disko": "disko",
|
||||
"flake-parts": "flake-parts",
|
||||
"nixos-generators": "nixos-generators",
|
||||
"nixpkgs": "nixpkgs",
|
||||
"sops-nix": "sops-nix",
|
||||
"treefmt-nix": "treefmt-nix"
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1713013053,
|
||||
"narHash": "sha256-ka9INCWd1jTPlK47gcuf1hrdPL7WcZ4UrN/bFHBCldU=",
|
||||
"ref": "refs/heads/main",
|
||||
"rev": "579994aea61b92d359d532a9cdc22fe4c4581c39",
|
||||
"revCount": 2536,
|
||||
"type": "git",
|
||||
"url": "https://git.clan.lol/clan/clan-core"
|
||||
},
|
||||
"original": {
|
||||
"type": "git",
|
||||
"url": "https://git.clan.lol/clan/clan-core"
|
||||
}
|
||||
},
|
||||
"disko": {
|
||||
"inputs": {
|
||||
"nixpkgs": [
|
||||
"clan-core",
|
||||
"nixpkgs"
|
||||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1712356478,
|
||||
"narHash": "sha256-kTcEtrQIRnexu5lAbLsmUcfR2CrmsACF1s3ZFw1NEVA=",
|
||||
"owner": "nix-community",
|
||||
"repo": "disko",
|
||||
"rev": "0a17298c0d96190ef3be729d594ba202b9c53beb",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "nix-community",
|
||||
"repo": "disko",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"flake-parts": {
|
||||
"inputs": {
|
||||
"nixpkgs-lib": [
|
||||
"clan-core",
|
||||
"nixpkgs"
|
||||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1712014858,
|
||||
"narHash": "sha256-sB4SWl2lX95bExY2gMFG5HIzvva5AVMJd4Igm+GpZNw=",
|
||||
"owner": "hercules-ci",
|
||||
"repo": "flake-parts",
|
||||
"rev": "9126214d0a59633752a136528f5f3b9aa8565b7d",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "hercules-ci",
|
||||
"repo": "flake-parts",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"nixlib": {
|
||||
"locked": {
|
||||
"lastModified": 1711846064,
|
||||
"narHash": "sha256-cqfX0QJNEnge3a77VnytM0Q6QZZ0DziFXt6tSCV8ZSc=",
|
||||
"owner": "nix-community",
|
||||
"repo": "nixpkgs.lib",
|
||||
"rev": "90b1a963ff84dc532db92f678296ff2499a60a87",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "nix-community",
|
||||
"repo": "nixpkgs.lib",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"nixos-generators": {
|
||||
"inputs": {
|
||||
"nixlib": "nixlib",
|
||||
"nixpkgs": [
|
||||
"clan-core",
|
||||
"nixpkgs"
|
||||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1712191720,
|
||||
"narHash": "sha256-xXtSSnVHURHsxLQO30dzCKW5NJVGV/umdQPmFjPFMVA=",
|
||||
"owner": "nix-community",
|
||||
"repo": "nixos-generators",
|
||||
"rev": "0c15e76bed5432d7775a22e8d22059511f59d23a",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "nix-community",
|
||||
"repo": "nixos-generators",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 1712468661,
|
||||
"narHash": "sha256-n2gVVBs+rV+HzPv/N3QQv5cdAXqSkjmaObvfeMqnw2c=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "298edc8f1e0dfffce67f50375c9f5952e04a6d02",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "NixOS",
|
||||
"ref": "nixos-unstable-small",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"root": {
|
||||
"inputs": {
|
||||
"clan-core": "clan-core"
|
||||
}
|
||||
},
|
||||
"sops-nix": {
|
||||
"inputs": {
|
||||
"nixpkgs": [
|
||||
"clan-core",
|
||||
"nixpkgs"
|
||||
],
|
||||
"nixpkgs-stable": [
|
||||
"clan-core"
|
||||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1712458908,
|
||||
"narHash": "sha256-DMgBS+jNHDg8z3g9GkwqL8xTKXCRQ/0FGsAyrniVonc=",
|
||||
"owner": "Mic92",
|
||||
"repo": "sops-nix",
|
||||
"rev": "39191e8e6265b106c9a2ba0cfd3a4dafe98a31c6",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "Mic92",
|
||||
"repo": "sops-nix",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"treefmt-nix": {
|
||||
"inputs": {
|
||||
"nixpkgs": [
|
||||
"clan-core",
|
||||
"nixpkgs"
|
||||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1711963903,
|
||||
"narHash": "sha256-N3QDhoaX+paWXHbEXZapqd1r95mdshxToGowtjtYkGI=",
|
||||
"owner": "numtide",
|
||||
"repo": "treefmt-nix",
|
||||
"rev": "49dc4a92b02b8e68798abd99184f228243b6e3ac",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "numtide",
|
||||
"repo": "treefmt-nix",
|
||||
"type": "github"
|
||||
}
|
||||
}
|
||||
},
|
||||
"root": "root",
|
||||
"version": 7
|
||||
}
|
||||
Loading…
Reference in New Issue
Block a user