diff --git a/docs/site/guides/getting-started/deploy.md b/docs/site/guides/getting-started/deploy.md index 6d26bff4f..cceaeadac 100644 --- a/docs/site/guides/getting-started/deploy.md +++ b/docs/site/guides/getting-started/deploy.md @@ -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,231 +10,180 @@ 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**" +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. - - [x] Any cloud machine if it is reachable via SSH and supports `kexec`. +Sample boot screen shows: - !!! 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) +- Root password +- IP address +- Optional Tor and mDNS details + +```{ .bash .annotate .no-copy .nohighlight} +┌─────────────────────────────────────────────────────────────────────────────────────┐ +│ ┌───────────────────────────┐ │ +│ │███████████████████████████│ # This is the QR Code (1) │ +│ │██ ▄▄▄▄▄ █▀▄█▀█▀▄█ ▄▄▄▄▄ ██│ │ +│ │██ █ █ █▀▄▄▄█ ▀█ █ █ ██│ │ +│ │██ █▄▄▄█ █▀▄ ▀▄▄▄█ █▄▄▄█ ██│ │ +│ │██▄▄▄▄▄▄▄█▄▀ ▀▄▀▄█▄▄▄▄▄▄▄██│ │ +│ │███▀▀▀ █▄▄█ ▀▄ ▄▀▄█ ███│ │ +│ │██▄██▄▄█▄▄▀▀██▄▀ ▄▄▄ ▄▀█▀██│ │ +│ │██ ▄▄▄▄▄ █▄▄▄▄ █ █▄█ █▀ ███│ │ +│ │██ █ █ █ █ █ ▄▄▄ ▄▀▀ ██│ │ +│ │██ █▄▄▄█ █ ▄ ▄ ▄ ▀█ ▄███│ │ +│ │██▄▄▄▄▄▄▄█▄▄▄▄▄▄█▄▄▄▄▄█▄███│ │ +│ │███████████████████████████│ │ +│ └───────────────────────────┘ │ +│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ +│ │Root password: cheesy-capital-unwell # password (2) │ │ +│ │Local network addresses: │ │ +│ │enp1s0 UP 192.168.178.169/24 metric 1024 fe80::21e:6ff:fe45:3c92/64 │ │ +│ │enp2s0 DOWN │ │ +│ │wlan0 DOWN # connect to wlan (3) │ │ +│ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion │ │ +│ │Multicast DNS: nixos-installer.local │ │ +│ └─────────────────────────────────────────────────────────────────────────────────┘ │ +│ Press 'Ctrl-C' for console access │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────────┘ +``` + +1. This is not an actual QR code, because it is displayed rather poorly on text sites. + This would be the actual content of this specific QR code prettified: + ```json + { + "pass": "cheesy-capital-unwell", + "tor": "6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion", + "addrs": [ + "2001:9e8:347:ca00:21e:6ff:fe45:3c92" + ] + } + ``` + + To generate the actual QR code, that would be displayed use: + ```shellSession + echo '{"pass":"cheesy-capital-unwell","tor":"6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion","addrs":["2001:9e8:347:ca00:21e:6ff:fe45:3c92"]}' | nix run nixpkgs#qrencode -- -s 2 -m 2 -t utf8 + ``` +2. The root password for the installer medium. + This password is autogenerated and meant to be easily typeable. +3. See [how to connect to wlan](./installer.md#optional-connect-to-wifi-manually). + +!!! tip + Use [KDE Connect](https://apps.kde.org/de/kdeconnect/) for easyily sharing QR codes from phone to desktop + +## Cloud VMs + +!!! 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` -=== "flake.nix (flake-parts)" +In your nix files set the targetHost (reachable ip) that you retrieved in the previous step. - ```{.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"; +```{.nix title="clan.nix" hl_lines="9"} +{ + # Ensure this is unique among all clans you want to use. + meta.name = "my-clan"; - 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 ]; + inventory.machines = { + # Define machines here. + # The machine name will be used as the hostname. + jon = { + deploy.targetHost = "root@192.168.192.4"; # (1) + }; + }; + # ... + # elided +} +``` - 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 - ; - }; - } - ``` +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. -## Identify the Target Disk +See also [how to set TargetHost](../target-host.md) for other methods. -On the setup computer, SSH into the target: +## Retrieve the hardware report -```bash title="setup computer" -ssh root@ lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT +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 ``` -Replace `` with the machine's IP or hostname if mDNS (i.e. Avahi) is available. +Example output: -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 +```shell-session +$ clan machines update-hardware-config jon +[jon] $ nixos-facter +Successfully generated: ./machines/jon/facter.json ``` -Look for the top-level disk device (e.g., nvme0n1 or sda) and copy its `ID-LINK`. Avoid using partition IDs like `nvme0n1p1`. +See [update-hardware-config cli reference](../../reference/cli/machines.md#machines-update-hardware-config) for further configuration possibilities if needed. -In this example we would copy `nvme-eui.e8238fa6bf530001001b448b4aec2929` +## 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). -## Fill in hardware specific machine configuration - -Edit the following fields inside the `./machines//configuration.nix` - - - -```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. - - Sample boot screen shows: - - - Root password - - IP address - - Optional Tor and mDNS details - - ```{ .bash .annotate .no-copy .nohighlight} - ┌─────────────────────────────────────────────────────────────────────────────────────┐ - │ ┌───────────────────────────┐ │ - │ │███████████████████████████│ # This is the QR Code (1) │ - │ │██ ▄▄▄▄▄ █▀▄█▀█▀▄█ ▄▄▄▄▄ ██│ │ - │ │██ █ █ █▀▄▄▄█ ▀█ █ █ ██│ │ - │ │██ █▄▄▄█ █▀▄ ▀▄▄▄█ █▄▄▄█ ██│ │ - │ │██▄▄▄▄▄▄▄█▄▀ ▀▄▀▄█▄▄▄▄▄▄▄██│ │ - │ │███▀▀▀ █▄▄█ ▀▄ ▄▀▄█ ███│ │ - │ │██▄██▄▄█▄▄▀▀██▄▀ ▄▄▄ ▄▀█▀██│ │ - │ │██ ▄▄▄▄▄ █▄▄▄▄ █ █▄█ █▀ ███│ │ - │ │██ █ █ █ █ █ ▄▄▄ ▄▀▀ ██│ │ - │ │██ █▄▄▄█ █ ▄ ▄ ▄ ▀█ ▄███│ │ - │ │██▄▄▄▄▄▄▄█▄▄▄▄▄▄█▄▄▄▄▄█▄███│ │ - │ │███████████████████████████│ │ - │ └───────────────────────────┘ │ - │ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ - │ │Root password: cheesy-capital-unwell # password (2) │ │ - │ │Local network addresses: │ │ - │ │enp1s0 UP 192.168.178.169/24 metric 1024 fe80::21e:6ff:fe45:3c92/64 │ │ - │ │enp2s0 DOWN │ │ - │ │wlan0 DOWN # connect to wlan (3) │ │ - │ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion │ │ - │ │Multicast DNS: nixos-installer.local │ │ - │ └─────────────────────────────────────────────────────────────────────────────────┘ │ - │ Press 'Ctrl-C' for console access │ - │ │ - └─────────────────────────────────────────────────────────────────────────────────────┘ - ``` - - 1. This is not an actual QR code, because it is displayed rather poorly on text sites. - This would be the actual content of this specific QR code prettified: - ```json - { - "pass": "cheesy-capital-unwell", - "tor": "6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion", - "addrs": [ - "2001:9e8:347:ca00:21e:6ff:fe45:3c92" - ] - } - ``` - - To generate the actual QR code, that would be displayed use: - ```shellSession - echo '{"pass":"cheesy-capital-unwell","tor":"6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion","addrs":["2001:9e8:347:ca00:21e:6ff:fe45:3c92"]}' | nix run nixpkgs#qrencode -- -s 2 -m 2 -t utf8 - ``` - 2. The root password for the installer medium. - This password is autogenerated and meant to be easily typeable. - 3. See [how to connect to wlan](./installer.md#optional-connect-to-wifi-manually). - - !!! tip - Use [KDE Connect](https://apps.kde.org/de/kdeconnect/) for easyily sharing QR codes from phone to desktop - -=== "**Cloud VM**" - - Just run the command **Option B: Cloud VM** below +**Finally deployment time!** Use one of the following commands to build and deploy the image via SSH onto your machine. ### Deployment Commands