┌─ docs/installation.md ─────────────────────────────────────────────────────┐│ diff --git a/docs/installation.md b/docs/installation.md ││ index 2f26198..c9ce31e 100644 ││ --- a/docs/installation.md ││ +++ b/docs/installation.md ││ @@ -3,7 +3,7 @@ ││ In this guide I will be going through a couple methods of installation and ││ deployment of an ooknet system. ││ ││ -## Basic install ││ +## Manual install ││ ││ **Assumptions**: ││ ││ @@ -23,7 +23,7 @@ If we intend to install onto a bare-metal machine the easiest me ││ thod would be to ││ flash the image onto a USB to be used as the boot device. This can be done ││ easily via the `dd` command: ││ ││ -##### Determine USB `/dev/` path ││ +#### Determine USB `/dev/` path ││ ││ Use the `lsblk` command to list out the current ││ ││ @@ -56,11 +56,11 @@ Run the following command to flash the USB with the installati ││ on image: ││ $ sudo dd bs=4M if=~/Downloads/latest-nixos-minimal-x86-64-linux.iso of=/dev/sda ││ status=progress && sync ││ ``` ││ ││ -#### Boot into install media ││ +### Boot into install media ││ ││ Using your host's BIOS (UEFI) boot manager, boot into the installation media. ││ ││ -#### Disk partitioning ││ +### Disk partitioning ││ ││ You will need to setup disk partitioning for the, how you partition a host is up ││ to you, in this example I will setup a basic btrfs setup: ││ @@ -84,8 +84,8 @@ In this case we will be using `nvme0n1` ││ ││ # here we are just settings up some optional environment variables to make the pa ││ rtitioning simpler ││ $ export D="/dev/nvme0n1" ││ -$ export P1=$D'p1 ││ -$ export P2=$D'p2' ││ +$ export P1=${D}p1 ││ +$ export P2=${D}p2 ││ $ export SWAP=4g ││ ``` ││ ││ @@ -118,11 +118,11 @@ $ sudo mount $P1 -m /mnt/boot ││ $ sudo btrfs filesystem mkswapfile --size $SWAP --uuid clear /mnt/swap/swapfile ││ ``` ││ ││ -#### Installing Nix ││ +### Installing Nix ││ ││ At this point if you would like to build the system directly from the ooknet ││ repository, you will need to obtain relevant ssh keys to decrypt the ││ -configurations secrtets. I recommend instead installing a minmal nixos ││ +configurations secrets. I recommend instead installing a minmal nixos ││ configuration, with a couple modifications. Then building from ooknet once ││ installed. ││ ││ @@ -198,3 +198,105 @@ After booting into the fresh installation you will need to a ││ uthenticate with ││ Following that, you can run: ││ ││ `sudo nixos-rebuild --flake github:ooks-io/ooknet#<hostname>` ││ + ││ +## Remote installation ││ + ││ +In most circumstances, provisioning a new host will be done remotely. These are ││ +the leverage a number of tools for remote provisioning: ││ + ││ +- Disko ││ + - declarative disk partitioning/formatting) ││ +- nixos-anywhere ││ + - script that manages, ssh connection, building/copying the system closure to ││ + remote host,and installing NixOS ││ +- 1Password ││ + - for fetching keys required for decrypting secrets ││ + ││ +### Pre-requisites ││ + ││ +In order to provision a new host remotely a number of requirements must be met. ││ + ││ +#### install-key ││ + ││ +The install-key is the ssh key that is used as identity to ssh into the ││ +ooknet-install-media as root. It can be obtained from the ooknet 1Password ││ +vault. ││ + ││ +#### Host disko configuration ││ + ││ +The host's configuration entry point must import a valid disko configuration. ││ + ││ +```nix ││ +{ ││ + imports = [ ││ + ./disko.nix ││ + ]; ││ +} ││ +``` ││ + ││ +An example disko configuration can be found ││ +[here](../modules/nixos/server/profiles/ookstest/disko.nix). ││ + ││ +#### Hardware.nix ││ + ││ +The entry point must also import a `hardware.nix` file, later this will be ││ +generated by nixos-anywhere. ││ + ││ +```nix ││ +{ ││ + imports = [ ││ + ./disko.nix ││ + ./hardware.nix ││ + ]; ││ +} ││ +``` ││ + ││ +#### Host keys ││ + ││ +We must generate the targets host keys prior to deployment as we use them during ││ +install to decrypt secrets. These host keys need to follow some rules: ││ + ││ +- Stored in the ooknet 1Password vault ││ +- tagged as "hostkey" ││ +- Naming convention must be "\<hostname\>-hostkey" ││ + ││ +Keys can be generated with `ssh-keygen` and manually added to 1Password, or most ││ +simply generated, stored, and tagged via the 1Password cli: ││ + ││ +```sh ││ +$ op item create \ ││ + --category=ssh \ ││ + --title="hostname-hostkey" \ ││ + --tags="hostkey" \ ││ + --vault="ooknet" ││ +``` ││ + ││ +See ││ +[1Password Documentation](https://developer.1password.com/docs/ssh/manage-keys/). ││ + ││ +#### Flake variable ││ + ││ +The $FLAKE environment variable must be set to the root of the ooknet flake. ││ + ││ +### Deploying system ││ + ││ +To deploy the system run the `ooknet-provision` command with the following ││ +options: ││ + ││ +``` ││ +$ ooknet-provision <hostname> <target ip> ││ +``` ││ + ││ +`ooknet-provision` has a couple optional flags to be aware of: ││ + ││ +- -v, --verbose) Enable verbose output ││ +- -d, --host-config-dir) Allow you to set the host configurations entry point, ││ + this will default to`$FLAKE/hosts/<hostname>` ││ +- -o, --extra-options) Allows you to pass additional flags to the nixos-anywhere ││ + command ││ + ││ +### ooknet-provision ││ + ││ +The `ooknet-provision` script is just a thin wrapper around nixos-anywhere, it ││ +runs a bunch of pre-deployment checks and handles the ssh host keys with ││ +1Password. │└────────────────────────────────────────────────────────────────────────────────────┘
┌─ docs/installation.md ───────────────┐│ diff --git a/docs/installation.md b/docs/ins ││ tallation.md ││ index 2f26198..c9ce31e 100644 ││ --- a/docs/installation.md ││ +++ b/docs/installation.md ││ @@ -3,7 +3,7 @@ ││ In this guide I will be going through a cou ││ ple methods of installation and ││ deployment of an ooknet system. ││ ││ -## Basic install ││ +## Manual install ││ ││ **Assumptions**: ││ ││ @@ -23,7 +23,7 @@ If we intend to install on ││ to a bare-metal machine the easiest method w ││ ould be to ││ flash the image onto a USB to be used as th ││ e boot device. This can be done ││ easily via the `dd` command: ││ ││ -##### Determine USB `/dev/` path ││ +#### Determine USB `/dev/` path ││ ││ Use the `lsblk` command to list out the cur ││ rent ││ ││ @@ -56,11 +56,11 @@ Run the following comman ││ d to flash the USB with the installation ima ││ ge: ││ $ sudo dd bs=4M if=~/Downloads/latest-nixos ││ -minimal-x86-64-linux.iso of=/dev/sda status ││ =progress && sync ││ ``` ││ ││ -#### Boot into install media ││ +### Boot into install media ││ ││ Using your host's BIOS (UEFI) boot manager, ││ boot into the installation media. ││ ││ -#### Disk partitioning ││ +### Disk partitioning ││ ││ You will need to setup disk partitioning fo ││ r the, how you partition a host is up ││ to you, in this example I will setup a basi ││ c btrfs setup: ││ @@ -84,8 +84,8 @@ In this case we will be us ││ ing `nvme0n1` ││ ││ # here we are just settings up some optiona ││ l environment variables to make the partitio ││ ning simpler ││ $ export D="/dev/nvme0n1" ││ -$ export P1=$D'p1 ││ -$ export P2=$D'p2' ││ +$ export P1=${D}p1 ││ +$ export P2=${D}p2 ││ $ export SWAP=4g ││ ``` ││ ││ @@ -118,11 +118,11 @@ $ sudo mount $P1 -m /m ││ nt/boot ││ $ sudo btrfs filesystem mkswapfile --size $ ││ SWAP --uuid clear /mnt/swap/swapfile ││ ``` ││ ││ -#### Installing Nix ││ +### Installing Nix ││ ││ At this point if you would like to build th ││ e system directly from the ooknet ││ repository, you will need to obtain relevan ││ t ssh keys to decrypt the ││ -configurations secrtets. I recommend instea ││ d installing a minmal nixos ││ +configurations secrets. I recommend instead ││ installing a minmal nixos ││ configuration, with a couple modifications. ││ Then building from ooknet once ││ installed. ││ ││ @@ -198,3 +198,105 @@ After booting into the ││ fresh installation you will need to authent ││ icate with ││ Following that, you can run: ││ ││ `sudo nixos-rebuild --flake github:ooks-io/ ││ ooknet#<hostname>` ││ + ││ +## Remote installation ││ + ││ +In most circumstances, provisioning a new h ││ ost will be done remotely. These are ││ +the leverage a number of tools for remote p ││ rovisioning: ││ + ││ +- Disko ││ + - declarative disk partitioning/formattin ││ g) ││ +- nixos-anywhere ││ + - script that manages, ssh connection, bu ││ ilding/copying the system closure to ││ + remote host,and installing NixOS ││ +- 1Password ││ + - for fetching keys required for decrypti ││ ng secrets ││ + ││ +### Pre-requisites ││ + ││ +In order to provision a new host remotely a ││ number of requirements must be met. ││ + ││ +#### install-key ││ + ││ +The install-key is the ssh key that is used ││ as identity to ssh into the ││ +ooknet-install-media as root. It can be obt ││ ained from the ooknet 1Password ││ +vault. ││ + ││ +#### Host disko configuration ││ + ││ +The host's configuration entry point must i ││ mport a valid disko configuration. ││ + ││ +```nix ││ +{ ││ + imports = [ ││ + ./disko.nix ││ + ]; ││ +} ││ +``` ││ + ││ +An example disko configuration can be found ││ +[here](../modules/nixos/server/profiles/ook ││ stest/disko.nix). ││ + ││ +#### Hardware.nix ││ + ││ +The entry point must also import a `hardwar ││ e.nix` file, later this will be ││ +generated by nixos-anywhere. ││ + ││ +```nix ││ +{ ││ + imports = [ ││ + ./disko.nix ││ + ./hardware.nix ││ + ]; ││ +} ││ +``` ││ + ││ +#### Host keys ││ + ││ +We must generate the targets host keys prio ││ r to deployment as we use them during ││ +install to decrypt secrets. These host keys ││ need to follow some rules: ││ + ││ +- Stored in the ooknet 1Password vault ││ +- tagged as "hostkey" ││ +- Naming convention must be "\<hostname\>-h ││ ostkey" ││ + ││ +Keys can be generated with `ssh-keygen` and ││ manually added to 1Password, or most ││ +simply generated, stored, and tagged via th ││ e 1Password cli: ││ + ││ +```sh ││ +$ op item create \ ││ + --category=ssh \ ││ + --title="hostname-hostkey" \ ││ + --tags="hostkey" \ ││ + --vault="ooknet" ││ +``` ││ + ││ +See ││ +[1Password Documentation](https://developer ││ .1password.com/docs/ssh/manage-keys/). ││ + ││ +#### Flake variable ││ + ││ +The $FLAKE environment variable must be set ││ to the root of the ooknet flake. ││ + ││ +### Deploying system ││ + ││ +To deploy the system run the `ooknet-provis ││ ion` command with the following ││ +options: ││ + ││ +``` ││ +$ ooknet-provision <hostname> <target ip> ││ +``` ││ + ││ +`ooknet-provision` has a couple optional fl ││ ags to be aware of: ││ + ││ +- -v, --verbose) Enable verbose output ││ +- -d, --host-config-dir) Allow you to set t ││ he host configurations entry point, ││ + this will default to`$FLAKE/hosts/<hostna ││ me>` ││ +- -o, --extra-options) Allows you to pass a ││ dditional flags to the nixos-anywhere ││ + command ││ + ││ +### ooknet-provision ││ + ││ +The `ooknet-provision` script is just a thi ││ n wrapper around nixos-anywhere, it ││ +runs a bunch of pre-deployment checks and h ││ andles the ssh host keys with ││ +1Password. │└──────────────────────────────────────────────┘