docs: improve tutorials
This commit is contained in:
parent
915864f637
commit
c4c843ba18
|
|
@ -1,13 +1,96 @@
|
|||
# Managing NixOS Machines with Clan
|
||||
|
||||
Integrating a new machine into your Clan environment is a very easy yet flexible process, allowing for the centralized management of multiple NixOS configurations.
|
||||
|
||||
We'll walk you through adding a new computer to your Clan using a special tool that works through a USB stick.
|
||||
|
||||
## Installing a New Machine
|
||||
|
||||
Clan CLI, in conjunction with [nixos-anywhere](https://github.com/nix-community/nixos-anywhere), provides a seamless method for installing NixOS on various machines.
|
||||
This process involves preparing a suitable hardware and disk partitioning configuration and ensuring the target machine is accessible via SSH.
|
||||
|
||||
### Prerequisites
|
||||
### Step 0. Prerequisites
|
||||
|
||||
- [x] A running Linux system with SSH on the target machine is required. This is typically pre-configured for many server providers.
|
||||
- [x] Two Computers: You'll need the computer you're setting up and another one to control the setup process. Both should be able to connect over the network using SSH. This is usually already done if you're working with servers from providers like Hetzner.
|
||||
- [x] A clan machine configuration you want to deploy. [Check out our templates](/templates/new-clan/flake.nix)
|
||||
- [x] Identify and prepare the USB Flash Drive
|
||||
|
||||
### Finishing the installation
|
||||
#### Prepare the USB Flash Drive
|
||||
|
||||
1. Insert your USB flash drive into your computer.
|
||||
|
||||
2. Identify your flash drive with `lsblk`
|
||||
|
||||
```shellSession
|
||||
$ lsblk
|
||||
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
|
||||
sdb 8:0 1 117,2G 0 disk
|
||||
└─sdb1 8:1 1 117,2G 0 part /run/media/qubasa/INTENSO
|
||||
nvme0n1 259:0 0 1,8T 0 disk
|
||||
├─nvme0n1p1 259:1 0 512M 0 part /boot
|
||||
└─nvme0n1p2 259:2 0 1,8T 0 part
|
||||
└─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0 0 1,8T 0 crypt /nix/store /
|
||||
```
|
||||
|
||||
In this case it's `sdb`
|
||||
|
||||
3. Ensure all partitions on the drive are unmounted. Replace `sdb1` in the command below with your device identifier (like `sdc1`, etc.):
|
||||
|
||||
```bash
|
||||
sudo umount /dev/sdb1
|
||||
```
|
||||
|
||||
## Creating a Bootable USB Drive on Linux
|
||||
|
||||
To create a bootable USB flash drive with the NixOS installer:
|
||||
|
||||
### Step 1. Build the Installer Image
|
||||
|
||||
```bash
|
||||
nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
|
||||
```
|
||||
|
||||
### Step 2. Write the Image to the USB Drive
|
||||
|
||||
Use the `dd` utility to write the NixOS installer image to your USB drive:
|
||||
|
||||
```bash
|
||||
sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sd<X>
|
||||
```
|
||||
|
||||
In case your USB device is `sdb` use `of=/dev/sdb`
|
||||
|
||||
### Step 3. Boot and Connect
|
||||
|
||||
After writing the installer to the USB drive, use it to boot the target machine.
|
||||
|
||||
> i.e. Plug it into the target machine and select the USB drive as a temporary boot device.
|
||||
|
||||
For most hardware you can find the Key-combination below:
|
||||
|
||||
- **Dell**: F12 (Boot Menu), F2/Del (BIOS Setup)
|
||||
- **HP**: F9 (Boot Menu), Esc (Startup Menu)
|
||||
- **Lenovo**: F12 (ThinkPad Boot Menu), F2/Fn+F2/Novo Button (IdeaPad Boot Menu/BIOS Setup)
|
||||
- **Acer**: F12 (Boot Menu), F2/Del (BIOS Setup)
|
||||
- **Asus**: F8/Esc (Boot Menu), F2/Del (BIOS Setup)
|
||||
- **Toshiba**: F12/F2 (Boot Menu), Esc then F12 (Alternate Method)
|
||||
- **Sony**: F11/Assist Button (Boot Menu/Recovery Options)
|
||||
- **Samsung**: F2/F12/Esc (Boot Menu), F2 (BIOS Setup)
|
||||
- **MSI**: F11 (Boot Menu), Del (BIOS Setup)
|
||||
- **Apple**: Option (Alt) Key (Boot Menu for Mac)
|
||||
- If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup.
|
||||
|
||||
**During Boot**
|
||||
|
||||
Select `NixOS` to boot into the clan installer
|
||||
|
||||
**After Booting**
|
||||
|
||||
The installer will display an IP address and a root password, which you can use to connect via SSH.
|
||||
|
||||
Alternatively you can also use the displayed QR code.
|
||||
|
||||
### Step 4. Finishing the installation
|
||||
|
||||
With the target machine running Linux and accessible via SSH, execute the following command to install NixOS on the target machine, replacing `<target_host>` with the machine's hostname or IP address:
|
||||
|
||||
|
|
@ -15,6 +98,20 @@ With the target machine running Linux and accessible via SSH, execute the follow
|
|||
clan machines install my-machine <target_host>
|
||||
```
|
||||
|
||||
#### 🎉 🚀 Your machine is all set up
|
||||
|
||||
---
|
||||
|
||||
## What's next ?
|
||||
|
||||
- [**Tweak Your Machine Setup**](#update-your-machines): Learn how to update an existing machine?
|
||||
|
||||
Coming Soon:
|
||||
|
||||
- **Join Your Machines in a Private Network:**: Stay tuned for steps on linking all your machines into a secure mesh network with Clan.
|
||||
|
||||
---
|
||||
|
||||
## Update Your Machines
|
||||
|
||||
Clan CLI enables you to remotely update your machines over SSH. This requires setting up a target address for each target machine.
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ cp -r /etc/nixos ~/nixos-backup
|
|||
|
||||
If you haven't yet adopted Nix Flakes in your project, follow these steps to initialize a new `flake.nix` file in your project directory.
|
||||
|
||||
> Note: Clan is based on flakes, it is possible to use cLan without flakes but not officially supported yet.
|
||||
> Note: Clan is based on flakes, it is possible to use Clan without flakes but not officially supported yet.
|
||||
|
||||
### Generate a Trivial flake.nix File
|
||||
|
||||
|
|
@ -81,13 +81,13 @@ path: <some/hash>
|
|||
|
||||
Create a directory where you put **all machine specific configs** like the `configuration.nix` or `hardware-configuration.nix`
|
||||
|
||||
> Following this structure will allow you nicely organize all your different machines and allows the cLan-CLI to automatically detect and manage your machines.
|
||||
> Following this structure will allow you nicely organize all your different machines and allows the Clan-CLI to automatically detect and manage your machines.
|
||||
|
||||
```bash
|
||||
mkdir -p machines/jons-desktop
|
||||
```
|
||||
|
||||
> In this case `jons-desktop` is the hostname of the machine you want to manage with cLan.
|
||||
> In this case `jons-desktop` is the hostname of the machine you want to manage with Clan.
|
||||
|
||||
Move your `configuration.nix` and included files into `machines/jons-desktop`
|
||||
|
||||
|
|
@ -213,11 +213,11 @@ This rebuilds your system configuration and switches to it.
|
|||
|
||||
## What's next?
|
||||
|
||||
After creating your cLan see [managing machines](./machines.md)
|
||||
After creating your Clan see [managing machines](./machines.md)
|
||||
|
||||
Or continue with **flake-parts integration**
|
||||
|
||||
## Integrating Clan with Flakes using `flake-parts``
|
||||
## Integrating Clan with Flakes using `flake-parts`
|
||||
|
||||
Clan supports integration with [flake.parts](https://flake.parts/) a tool which allows modular compositions.
|
||||
|
||||
|
|
@ -286,7 +286,7 @@ Below is a guide on how to structure this in your flake.nix:
|
|||
jons-desktop = {
|
||||
nixpkgs.hostPlatform = "x86_64-linux";
|
||||
imports = [
|
||||
clan-core.clanModules.sshd # Add openssh server for cLan management
|
||||
clan-core.clanModules.sshd # Add openssh server for Clan management
|
||||
./configuration.nix
|
||||
];
|
||||
};
|
||||
|
|
@ -307,6 +307,6 @@ With your flake created, explore how to add new machines by reviewing the docume
|
|||
|
||||
## TODO
|
||||
|
||||
* How do I use cLan machines install to setup my current machine?
|
||||
* How do I use Clan machines install to setup my current machine?
|
||||
* I probably need the clan-core sshd module for that?
|
||||
* We need to tell them that configuration.nix of a machine NEEDS to be under the directory CLAN_ROOT/machines/<machine-name> I think?
|
||||
|
|
@ -1,49 +1,61 @@
|
|||
# **Quick Start Guide to Initializing a New Clan Project**
|
||||
# Getting Started with Your First Clan Project
|
||||
|
||||
This guide will lead you through initiating a new Clan project
|
||||
Welcome to your simple guide on starting a new Clan project!
|
||||
|
||||
## **Overview**
|
||||
## What's Inside
|
||||
|
||||
Dive into our structured guide tailored to meet your needs:
|
||||
We've put together a straightforward guide to help you out:
|
||||
|
||||
- [**Starting with a New Clan Project**](#starting-with-a-new-clan-project): Kickstart your journey with Clan by setting up a new project from the ground up.
|
||||
- [**Migrating Existing Flake Configuration**](migrate.md#migrating-existing-nixos-configuration-flake): Transition your existing flake-based Nix configuration to harness the power of Clan Core.
|
||||
- [**Integrating Clan using Flake-Parts**](./migrate.md#integrating-clan-with-flakes-using-flake-parts): Enhance your Clan experience by integrating it with Flake-Parts.
|
||||
- [**Starting with a New Clan Project**](#starting-with-a-new-clan-project): Create a new Clan from scratch.
|
||||
- [**Migrating Existing Flake Configuration**](migrate.md#migrating-existing-nixos-configuration-flake): How to switch your current setup to a Clan setup.
|
||||
- [**Integrating Clan using Flake-Parts**](./migrate.md#integrating-clan-with-flakes-using-flake-parts)
|
||||
|
||||
---
|
||||
|
||||
## **Starting with a New Clan Project**
|
||||
## Starting with a New Clan Project
|
||||
|
||||
Embark on your Clan adventure with these initial steps:
|
||||
Create your own clan with these initial steps:
|
||||
|
||||
### Step 1: Add Clan CLI to Your Shell
|
||||
|
||||
Add the Clan CLI into your development workflow:
|
||||
|
||||
### **Step 1: Add Clan CLI to Your Shell**
|
||||
Incorporate the Clan CLI into your development workflow with this simple command:
|
||||
```shell
|
||||
nix shell git+https://git.clan.lol/clan/clan-core
|
||||
```
|
||||
|
||||
### **Step 2: Initialize Your Project**
|
||||
Set the foundation of your Clan project by initializing it as follows:
|
||||
### Step 2: Initialize Your Project
|
||||
|
||||
Set the foundation of your Clan project by initializing it as follows
|
||||
|
||||
```shell
|
||||
clan flakes create my-clan
|
||||
```
|
||||
This command crafts the essential `flake.nix` and `.clan-flake` files for your project.
|
||||
|
||||
### **Step 3: Verify the Project Structure**
|
||||
Ensure the creation of your project files with a quick directory listing:
|
||||
This command creates the `flake.nix` and `.clan-flake` files for your project.
|
||||
|
||||
### Step 3: Verify the Project Structure
|
||||
|
||||
Ensure the creation of your project files with a quick directory listing
|
||||
|
||||
```shell
|
||||
cd my-clan && ls -la
|
||||
```
|
||||
Look for `.clan-flake`, `flake.lock`, and `flake.nix` among your files to confirm successful setup.
|
||||
|
||||
### **Understanding `.clan-flake`**
|
||||
The `.clan-flake` file, while optional, is instrumental in helping the Clan CLI identify your project's root directory, easing project management.
|
||||
You should see `.clan-flake`, `flake.lock`, and `flake.nix` among the files listed, which means you're all set up!
|
||||
|
||||
---
|
||||
|
||||
### Next Steps
|
||||
|
||||
### 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.**
|
||||
|
||||
**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](./install-iso.md) that automatically generates an endpoint reachable over TOR with a random ssh password.
|
||||
|
||||
On the remote execute:
|
||||
|
|
@ -72,5 +84,10 @@ On the remote execute:
|
|||
|
||||
### **Next Steps**
|
||||
Ready to expand? Explore how to install a new machine with the helpful documentation [here](./machines.md).
|
||||
Ready to explore more?
|
||||
|
||||
- **Adding New Machines to your setup**. [Following our template](/templates/new-clan/flake.nix)
|
||||
|
||||
- **Use a USB drive to Set Up Machines**: Setting up new computers remotely is easy with a USB stick. [Learn how] (./machines.md).
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -24,25 +24,25 @@
|
|||
./machines/jon/configuration.nix
|
||||
clan-core.clanModules.sshd
|
||||
clan-core.clanModules.diskLayouts
|
||||
{
|
||||
config.clanCore.machineIcon = null; # Optional, a path to an image file
|
||||
|
||||
# Set this for clan commands use ssh i.e. `clan machines update`
|
||||
config.clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
|
||||
|
||||
# TODO: Example how to use disko for more complicated setups
|
||||
|
||||
# remote> lsblk --output NAME,PTUUID,FSTYPE,SIZE,MOUNTPOINT
|
||||
config.clan.diskLayouts.singleDiskExt4 = {
|
||||
device = "/dev/disk/by-id/__CHANGE_ME__";
|
||||
};
|
||||
|
||||
config.services.getty.autologinUser = "root";
|
||||
|
||||
# TODO: Document that there needs to be one controller
|
||||
config.clan.networking.zerotier.controller.enable = true;
|
||||
}
|
||||
];
|
||||
config = {
|
||||
clanCore.machineIcon = null; # Optional, a path to an image file
|
||||
|
||||
# Set this for clan commands use ssh i.e. `clan machines update`
|
||||
clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
|
||||
|
||||
# TODO: Example how to use disko for more complicated setups
|
||||
|
||||
# remote> lsblk --output NAME,PTUUID,FSTYPE,SIZE,MOUNTPOINT
|
||||
clan.diskLayouts.singleDiskExt4 = {
|
||||
device = "/dev/disk/by-id/__CHANGE_ME__";
|
||||
};
|
||||
|
||||
services.getty.autologinUser = "root";
|
||||
|
||||
# TODO: Document that there needs to be one controller
|
||||
clan.networking.zerotier.controller.enable = true;
|
||||
};
|
||||
};
|
||||
sara = {
|
||||
nixpkgs.hostPlatform = system;
|
||||
|
|
@ -50,19 +50,19 @@
|
|||
./machines/sara/configuration.nix
|
||||
clan-core.clanModules.sshd
|
||||
clan-core.clanModules.diskLayouts
|
||||
{
|
||||
config.clanCore.machineIcon = null; # Optional, a path to an image file
|
||||
|
||||
# Set this for clan commands use ssh i.e. `clan machines update`
|
||||
config.clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
|
||||
|
||||
# local> clan facts generate
|
||||
|
||||
config.clan.diskLayouts.singleDiskExt4 = {
|
||||
device = "/dev/disk/by-id/__CHANGE_ME__";
|
||||
};
|
||||
}
|
||||
];
|
||||
config = {
|
||||
clanCore.machineIcon = null; # Optional, a path to an image file
|
||||
|
||||
# Set this for clan commands use ssh i.e. `clan machines update`
|
||||
clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
|
||||
|
||||
# local> clan facts generate
|
||||
|
||||
clan.diskLayouts.singleDiskExt4 = {
|
||||
device = "/dev/disk/by-id/__CHANGE_ME__";
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
{
|
||||
config.disko.devices = {
|
||||
disko.devices = {
|
||||
disk = {
|
||||
main = {
|
||||
type = "disk";
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user