Docs: rewrite deployment instructions
This commit is contained in:
Johannes Kirschbauer
@@ -1,6 +1,6 @@
|
|||||||
# Deploy a machine
|
# 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
|
## Prerequisites
|
||||||
|
|
||||||
@@ -10,206 +10,58 @@ 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] **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.
|
- [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."
|
- Root password
|
||||||
If on Linode: Make sure that the system uses Direct Disk boot kernel (found in the configuration pannel)
|
- IP address
|
||||||
|
- Optional Tor and mDNS details
|
||||||
|
|
||||||
## Setting `targetHost`
|
```{ .bash .annotate .no-copy .nohighlight}
|
||||||
|
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
||||||
=== "flake.nix (flake-parts)"
|
│ ┌───────────────────────────┐ │
|
||||||
|
│ │███████████████████████████│ # This is the QR Code (1) │
|
||||||
```{.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"
|
│ │Root password: cheesy-capital-unwell # password (2) │ │
|
||||||
"aarch64-darwin"
|
│ │Local network addresses: │ │
|
||||||
];
|
│ │enp1s0 UP 192.168.178.169/24 metric 1024 fe80::21e:6ff:fe45:3c92/64 │ │
|
||||||
imports = [ inputs.clan-core.flakeModules.default ];
|
│ │enp2s0 DOWN │ │
|
||||||
|
│ │wlan0 DOWN # connect to wlan (3) │ │
|
||||||
clan = {
|
│ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion │ │
|
||||||
inventory.machines = {
|
│ │Multicast DNS: nixos-installer.local │ │
|
||||||
jon = {
|
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
|
||||||
# targetHost will get picked up by cli commands
|
│ Press 'Ctrl-C' for console access │
|
||||||
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.
|
1. This is not an actual QR code, because it is displayed rather poorly on text sites.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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:
|
This would be the actual content of this specific QR code prettified:
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
@@ -225,16 +77,113 @@ Edit the following fields inside the `./machines/<machine_name>/configuration.ni
|
|||||||
```shellSession
|
```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
|
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.
|
2. The root password for the installer medium.
|
||||||
This password is autogenerated and meant to be easily typeable.
|
This password is autogenerated and meant to be easily typeable.
|
||||||
3. See [how to connect to wlan](./installer.md#optional-connect-to-wifi-manually).
|
3. See [how to connect to wlan](./installer.md#optional-connect-to-wifi-manually).
|
||||||
|
|
||||||
!!! tip
|
!!! tip
|
||||||
Use [KDE Connect](https://apps.kde.org/de/kdeconnect/) for easyily sharing QR codes from phone to desktop
|
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
|
### Deployment Commands
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user