Docs: rewrite deployment instructions
This commit is contained in:
Johannes Kirschbauer
@@ -1,6 +1,6 @@
|
||||
# Deploy a machine
|
||||
|
||||
Now that you have created a new machine, we will walk through how to install it.
|
||||
Now that you have created a machines, added some services and setup secrets. This guide will walk through how to deploy it.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -10,165 +10,17 @@ Now that you have created a new machine, we will walk through how to install it.
|
||||
- [x] **Machine configuration**: See our basic [adding and configuring machine guide](./add-machines.md)
|
||||
- [x] **Initialized secrets**: See [secrets](secrets.md) for how to initialize your secrets.
|
||||
|
||||
=== "**Physical Hardware**"
|
||||
## Physical Hardware
|
||||
|
||||
- [x] **USB Flash Drive**: See [Clan Installer](installer.md)
|
||||
!!! note "skip this if using a cloud VM"
|
||||
|
||||
!!! Steps
|
||||
Steps:
|
||||
|
||||
1. Create a NixOS installer image and transfer it to a bootable USB drive as described in the [installer](./installer.md).
|
||||
- Create a NixOS installer image and transfer it to a bootable USB drive as described in the [installer](./installer.md).
|
||||
- Boot the target machine and connect it to a network that makes it reachable from your setup computer.
|
||||
- Note down a reachable ip adress (*ipv4*, *ipv6* or *tor*)
|
||||
|
||||
2. Boot the target machine and connect it to a network that makes it reachable from your setup computer.
|
||||
|
||||
=== "**Cloud VMs**"
|
||||
|
||||
- [x] Any cloud machine if it is reachable via SSH and supports `kexec`.
|
||||
|
||||
!!! Warning "NixOS can cause strange issues when booting in certain cloud environments."
|
||||
If on Linode: Make sure that the system uses Direct Disk boot kernel (found in the configuration pannel)
|
||||
|
||||
## Setting `targetHost`
|
||||
|
||||
=== "flake.nix (flake-parts)"
|
||||
|
||||
```{.nix hl_lines="22"}
|
||||
{
|
||||
inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
|
||||
inputs.nixpkgs.follows = "clan-core/nixpkgs";
|
||||
inputs.flake-parts.follows = "clan-core/flake-parts";
|
||||
inputs.flake-parts.inputs.nixpkgs-lib.follows = "clan-core/nixpkgs";
|
||||
|
||||
outputs =
|
||||
inputs@{ flake-parts, ... }:
|
||||
flake-parts.lib.mkFlake { inherit inputs; } {
|
||||
systems = [
|
||||
"x86_64-linux"
|
||||
"aarch64-linux"
|
||||
"x86_64-darwin"
|
||||
"aarch64-darwin"
|
||||
];
|
||||
imports = [ inputs.clan-core.flakeModules.default ];
|
||||
|
||||
clan = {
|
||||
inventory.machines = {
|
||||
jon = {
|
||||
# targetHost will get picked up by cli commands
|
||||
deploy.targetHost = "root@jon";
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
=== "flake.nix (classic)"
|
||||
|
||||
```{.nix hl_lines="14"}
|
||||
{
|
||||
inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
|
||||
inputs.nixpkgs.follows = "clan-core/nixpkgs";
|
||||
|
||||
outputs =
|
||||
{ self, clan-core, ... }:
|
||||
let
|
||||
clan = clan-core.lib.clan {
|
||||
inherit self;
|
||||
|
||||
inventory.machines = {
|
||||
jon = {
|
||||
# targetHost will get picked up by cli commands
|
||||
deploy.targetHost = "root@jon";
|
||||
};
|
||||
};
|
||||
};
|
||||
in
|
||||
{
|
||||
inherit (clan.config)
|
||||
nixosConfigurations
|
||||
nixosModules
|
||||
clanInternals
|
||||
darwinConfigurations
|
||||
darwinModules
|
||||
;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
!!! warning
|
||||
The use of `root@` in the target address implies SSH access as the `root` user.
|
||||
Ensure that the root login is secured and only used when necessary.
|
||||
|
||||
## Identify the Target Disk
|
||||
|
||||
On the setup computer, SSH into the target:
|
||||
|
||||
```bash title="setup computer"
|
||||
ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
|
||||
```
|
||||
|
||||
Replace `<IP>` with the machine's IP or hostname if mDNS (i.e. Avahi) is available.
|
||||
|
||||
Which should show something like:
|
||||
|
||||
```{.shellSession hl_lines="6" .no-copy}
|
||||
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
|
||||
```
|
||||
|
||||
Look for the top-level disk device (e.g., nvme0n1 or sda) and copy its `ID-LINK`. Avoid using partition IDs like `nvme0n1p1`.
|
||||
|
||||
In this example we would copy `nvme-eui.e8238fa6bf530001001b448b4aec2929`
|
||||
|
||||
!!! tip
|
||||
For advanced partitioning, see [Disko templates](https://github.com/nix-community/disko-templates) or [Disko examples](https://github.com/nix-community/disko/tree/master/example).
|
||||
|
||||
## Fill in hardware specific machine configuration
|
||||
|
||||
Edit the following fields inside the `./machines/<machine_name>/configuration.nix`
|
||||
|
||||
<!-- Note: Use "jon" instead of "<machine>" as "<" is not supported in title tag -->
|
||||
|
||||
```nix title="./machines/jon/configuration.nix" hl_lines="12 15 19"
|
||||
{
|
||||
imports = [
|
||||
# contains your disk format and partitioning configuration.
|
||||
../../modules/disko.nix
|
||||
# this file is shared among all machines
|
||||
../../modules/shared.nix
|
||||
# enables GNOME desktop (optional)
|
||||
../../modules/gnome.nix
|
||||
];
|
||||
|
||||
# Put your username here for login
|
||||
users.users.user.name = "__YOUR_USERNAME__";
|
||||
|
||||
# Replace this __CHANGE_ME__ with the copied result of the lsblk command
|
||||
disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
|
||||
|
||||
# IMPORTANT! Add your SSH key here
|
||||
# e.g. > cat ~/.ssh/id_ed25519.pub
|
||||
users.users.root.openssh.authorizedKeys.keys = [ "__YOUR_SSH_KEY__" ];
|
||||
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
!!! Info "Replace `__YOUR_USERNAME__` with the ip of your machine, if you use avahi you can also use your hostname"
|
||||
!!! Info "Replace `__CHANGE_ME__` with the appropriate `ID-LINK` identifier, such as `nvme-eui.e8238fa6bf530001001b448b4aec2929`"
|
||||
!!! Info "Replace `__YOUR_SSH_KEY__` with your personal key, like `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILoMI0NC5eT9pHlQExrvR5ASV3iW9+BXwhfchq0smXUJ jon@jon-desktop`"
|
||||
|
||||
## Deploy the machine
|
||||
|
||||
**Finally deployment time!** Use the following command to build and deploy the image via SSH onto your machine.
|
||||
|
||||
=== "**Image Installer**"
|
||||
---
|
||||
|
||||
The installer will generate a password and local addresses on boot, then run ssh with these preconfigured.
|
||||
The installer shows it's deployment relevant information in two formats, a text form, as well as a QR code.
|
||||
@@ -232,9 +84,106 @@ Edit the following fields inside the `./machines/<machine_name>/configuration.ni
|
||||
!!! tip
|
||||
Use [KDE Connect](https://apps.kde.org/de/kdeconnect/) for easyily sharing QR codes from phone to desktop
|
||||
|
||||
=== "**Cloud VM**"
|
||||
## Cloud VMs
|
||||
|
||||
Just run the command **Option B: Cloud VM** below
|
||||
!!! note "skip this if using a physical machine"
|
||||
|
||||
Clan supports any cloud machine if it is reachable via SSH and supports `kexec`.
|
||||
|
||||
Steps:
|
||||
|
||||
- Go to the configuration panel and note down how to connect to the machine via ssh.
|
||||
|
||||
!!! tip "NixOS can cause strange issues when booting in certain cloud environments."
|
||||
If on Linode: Make sure that the system uses "Direct Disk boot kernel" (found in the configuration panel)
|
||||
|
||||
## Setting `targetHost`
|
||||
|
||||
In your nix files set the targetHost (reachable ip) that you retrieved in the previous step.
|
||||
|
||||
```{.nix title="clan.nix" hl_lines="9"}
|
||||
{
|
||||
# Ensure this is unique among all clans you want to use.
|
||||
meta.name = "my-clan";
|
||||
|
||||
inventory.machines = {
|
||||
# Define machines here.
|
||||
# The machine name will be used as the hostname.
|
||||
jon = {
|
||||
deploy.targetHost = "root@192.168.192.4"; # (1)
|
||||
};
|
||||
};
|
||||
# ...
|
||||
# elided
|
||||
}
|
||||
```
|
||||
|
||||
1. Use the ip address of your targetMachine that you want to deploy. If using the [flash-installer](./installer.md) it should display its local ip-address when booted.
|
||||
|
||||
!!! warning
|
||||
The use of `root@` in the target address implies SSH access as the `root` user.
|
||||
Ensure that the root login is secured and only used when necessary.
|
||||
|
||||
See also [how to set TargetHost](../target-host.md) for other methods.
|
||||
|
||||
## Retrieve the hardware report
|
||||
|
||||
By default clan uses [nixos-facter](https://github.com/nix-community/nixos-facter) which captures detailed information about the machine or virtual environment.
|
||||
|
||||
To generate the hardware-report (`facter.json`) run:
|
||||
|
||||
```bash
|
||||
clan machines update-hardware-config <machineName>
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```shell-session
|
||||
$ clan machines update-hardware-config jon
|
||||
[jon] $ nixos-facter
|
||||
Successfully generated: ./machines/jon/facter.json
|
||||
```
|
||||
|
||||
See [update-hardware-config cli reference](../../reference/cli/machines.md#machines-update-hardware-config) for further configuration possibilities if needed.
|
||||
|
||||
## Configure your disk schema
|
||||
|
||||
By default clan uses [disko](https://github.com/nix-community/disko) which allows for declarative disk partitioning.
|
||||
|
||||
To setup a disk schema for a machine run
|
||||
|
||||
```bash
|
||||
clan templates apply disk --to-machine jon --template single-disk --set mainDisk ""
|
||||
```
|
||||
|
||||
Which should fail and give the valid options for the specific hardware:
|
||||
|
||||
```terminal-session
|
||||
Invalid value for placeholder mainDisk - Valid options:
|
||||
/dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368
|
||||
```
|
||||
|
||||
Re-run the command with the correct disk:
|
||||
|
||||
```bash
|
||||
clan templates apply disk --to-machine jon --template single-disk --set mainDisk "/dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368"
|
||||
```
|
||||
|
||||
Should now be succesfull
|
||||
|
||||
```terminal-session
|
||||
Applied disk template 'single-disk' to machine 'jon'
|
||||
```
|
||||
|
||||
A disko.nix file should be created in `machines/jon`
|
||||
You can have a look and customize it if needed.
|
||||
|
||||
!!! tip
|
||||
For advanced partitioning, see [Disko templates](https://github.com/nix-community/disko-templates) or [Disko examples](https://github.com/nix-community/disko/tree/master/example).
|
||||
|
||||
## Deploy the machine
|
||||
|
||||
**Finally deployment time!** Use one of the following commands to build and deploy the image via SSH onto your machine.
|
||||
|
||||
### Deployment Commands
|
||||
|
||||
|
||||
Reference in New Issue
Block a user