┌─ docs/installation.md ─────────────────────────────────────────────────────┐│ diff --git a/docs/installation.md b/docs/installation.md ││ index 7b8394b..2f26198 100644 ││ --- a/docs/installation.md ││ +++ b/docs/installation.md ││ @@ -1,43 +1,200 @@ ││ -# Basic install ││ +# Installation and deployment ││ ││ -## Partitioning ││ +In this guide I will be going through a couple methods of installation and ││ +deployment of an ooknet system. ││ ││ -Partitioning will depend on the drive you have, here is an example of a simple ││ -partitioning scheme for a single drive. ││ +## Basic install ││ + ││ +**Assumptions**: ││ + ││ +- We are starting fresh with no current installation of NixOS available ││ +- We are already using a UNIX environment with access to the command: `lsblk` ││ + and `dd` ││ + ││ +### Obtaining a NixOS installation media ││ + ││ +#### Flashing a USB ││ + ││ +> [!WARN] ││ +> The following assumes you are already currently using an installation of ││ +> linux, if not, alternative methods of usb flashing will be required. ││ + ││ +If we intend to install onto a bare-metal machine the easiest method 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 ││ + ││ +Use the `lsblk` command to list out the current ││ + ││ +```sh ││ +$ lsblk ││ +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS ││ +sda 8:0 1 57.3G 0 disk ││ +├─sda1 8:1 1 1.1G 0 part ││ +└─sda2 8:2 1 3M 0 part ││ +nvme0n1 259:0 0 931.5G 0 disk ││ +├─nvme0n1p1 259:1 0 512M 0 part /boot ││ +└─nvme0n1p2 259:2 0 931G 0 part ││ + └─cryptroot 254:0 0 931G 0 crypt /persist ││ +``` ││ + ││ +Here we can see that `sda` is the intended target for our usb, so the full path ││ +would be `/dev/sda` ││ + ││ +#### Obtain install image ││ + ││ +Download the ││ +[Minimal NixOS Install Image](https://channels.nixos.org/nixos-24.11/latest-nixos ││ -minimal-x86_64-linux.iso). ││ + ││ +#### Flash the USB ││ + ││ +Run the following command to flash the USB with the installation image: ││ ││ ```sh ││ -# what drive we are using ││ -export D="/dev/vda" ││ -export D1=$D'1' ││ -export D2=$D'2' ││ +# Assuming the iso was downloaded to ~/Downloads/latest-nixos-minimal-x86-64-linu ││ x.iso ││ +$ sudo dd bs=4M if=~/Downloads/latest-nixos-minimal-x86-64-linux.iso of=/dev/sda ││ status=progress && sync ││ +``` ││ ││ -# size of the swap for example 1GiB swap would be: ││ -export SWAP=1g ││ -sudo parted -s $D mklabel gpt mkpart "EFI" fat32 1MiB 513MiB mkpart "NixOS" btrfs ││ 513MiB 100% set 1 esp on ││ -sudo mkfs.fat -F 32 $D1 && sudo mkfs.btrfs -f $D2 ││ +#### Boot into install media ││ ││ -sudo mount $D2 -m /mnt ││ +Using your host's BIOS (UEFI) boot manager, boot into the installation media. ││ ││ -sudo btrfs subvolume create /mnt/root ││ -sudo btrfs subvolume create /mnt/home ││ -sudo btrfs subvolume create /mnt/nix ││ -sudo btrfs subvolume create /mnt/swap ││ +#### Disk partitioning ││ ││ -sudo umount /mnt ││ +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: ││ ││ -sudo mount -o subvol=root $D2 -m /mnt ││ -sudo mount -o subvol=home $D2 -m /mnt/home ││ -sudo mount -o subvol=nix $D2 -m /mnt/nix ││ -sudo mount -o subvol=swap $D2 -m /mnt/swap ││ -sudo mount $D1 -m /mnt/boot ││ +Use `lsblk` to determine the target disk we want to partition ││ ││ -sudo btrfs filesystem mkswapfilee --size $SWAP --uuid clear /mnt/swap/swapfile ││ +```sh ││ +$ lsblk ││ + ││ +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS ││ +sda 8:0 1 57.3G 0 disk ││ +├─sda1 8:1 1 1.1G 0 part ││ +└─sda2 8:2 1 3M 0 part ││ +nvme0n1 259:0 0 931.5G 0 disk ││ ``` ││ ││ -## Installing Nix ││ +In this case we will be using `nvme0n1` ││ ││ ```sh ││ -sudo nixos-generate-conig --root /mnt ││ -sudo nixos-install ││ -# done ││ +# if you would like to avoid using sudo repeatedly, you can opt to run sudo -i to ││ login as root. In the following example I will opt not too use sudo -i ││ + ││ +# 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 SWAP=4g ││ ``` ││ + ││ +Formatting and mounting ││ + ││ +```sh ││ +# partition drive ││ +$ sudo parted \ ││ +-s $D mklabel gpt \ ││ +mkpart "EFI" fat32 1MiB 513MiB \ # boot partition ││ +mkpart "NixOS" btrfs 513MiB 100% set 1 esp on # root partition ││ + ││ +$ sudo mkfs.fat -F 32 $P1 && sudo mkfs.btrfs -f $P2 # define partition filesystem ││ + ││ +# mount drives to create subvolumes ││ +$ sudo mount $P2 -m /mnt ││ + ││ +# define subvolumes ││ +$ sudo btrfs subvolume create /mnt/{root,nix,home,swap} ││ + ││ +$ sudo umount /mnt ││ + ││ +# mount all subvolumes to there respective paths, making the directories if neede ││ d ││ +$ sudo mount -o subvol={root,home,nix,swap} $P2 -m /mnt{,/home,/nix,/swap} ││ + ││ +# mount boot ││ +$ sudo mount $P1 -m /mnt/boot ││ + ││ +# create swap file ││ +$ sudo btrfs filesystem mkswapfile --size $SWAP --uuid clear /mnt/swap/swapfile ││ +``` ││ + ││ +#### 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 ││ +configuration, with a couple modifications. Then building from ooknet once ││ +installed. ││ + ││ +```sh ││ +# generate hordware-configuration.nix ││ +$ sudo nixos-generate-config --root /mnt ││ +``` ││ + ││ +Using preferred text editor, add the following to ││ +`/mnt/etc/nixos/configuration.nix`: ││ + ││ +```nix ││ +# setup "wheel" user ││ +users.users.ooks = { ││ + isNormalUser = true; ││ + extraGroups = ["wheel" "video" "audio"]; ││ +}; ││ +# configure 1Password module, this will be used to obtain secrets to install the ││ intended host configuration ││ +programs = { ││ + _1password.enable = true; ││ + _1password-gui = { ││ + enable = true; ││ + polkitPolicyOwners = ["ooks"]; ││ + }; ││ +}; ││ +``` ││ + ││ +You will also need some sort of graphical environment to boot into, I recommend ││ +something simple like gnome ││ + ││ +```nix ││ +services.xserver = { ││ + enable = true; ││ + displayManager.gdm.enable = true; ││ + desktopManager.gnome.enable = true; ││ +}; ││ +# disable unnecessary gnome packages ││ +environment.gnome.excludePackages = with pkgs; [ ││ + orca ││ + epiphany ││ + evince ││ + gedit ││ + gnome-music ││ + gnome-photos ││ + gnome-terminal ││ + gnome-tour ││ + hitori ││ + iagno ││ + tali ││ + atomix ││ +]; ││ +``` ││ + ││ +Install the system ││ + ││ +```sh ││ +$ sudo nixos-install ││ +``` ││ + ││ +Set a password for the user ││ + ││ +```sh ││ +$ sudo nixos-enter --root /mnt -c 'passwd ooks' ││ +``` ││ + ││ +Reboot the system ││ + ││ +#### Post install ││ + ││ +After booting into the fresh installation you will need to authenticate with ││ +1Password and move the ssh keys required for secret decryption into ~/.ssh. ││ + ││ +Following that, you can run: ││ + ││ +`sudo nixos-rebuild --flake github:ooks-io/ooknet#<hostname>` │└────────────────────────────────────────────────────────────────────────────────────┘
┌─ docs/installation.md ───────────────┐│ diff --git a/docs/installation.md b/docs/ins ││ tallation.md ││ index 7b8394b..2f26198 100644 ││ --- a/docs/installation.md ││ +++ b/docs/installation.md ││ @@ -1,43 +1,200 @@ ││ -# Basic install ││ +# Installation and deployment ││ ││ -## Partitioning ││ +In this guide I will be going through a cou ││ ple methods of installation and ││ +deployment of an ooknet system. ││ ││ -Partitioning will depend on the drive you h ││ ave, here is an example of a simple ││ -partitioning scheme for a single drive. ││ +## Basic install ││ + ││ +**Assumptions**: ││ + ││ +- We are starting fresh with no current ins ││ tallation of NixOS available ││ +- We are already using a UNIX environment w ││ ith access to the command: `lsblk` ││ + and `dd` ││ + ││ +### Obtaining a NixOS installation media ││ + ││ +#### Flashing a USB ││ + ││ +> [!WARN] ││ +> The following assumes you are already cur ││ rently using an installation of ││ +> linux, if not, alternative methods of usb ││ flashing will be required. ││ + ││ +If we intend to install onto a bare-metal m ││ achine the easiest method would 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 ││ + ││ +Use the `lsblk` command to list out the cur ││ rent ││ + ││ +```sh ││ +$ lsblk ││ +NAME MAJ:MIN RM SIZE RO TYPE MO ││ UNTPOINTS ││ +sda 8:0 1 57.3G 0 disk ││ +├─sda1 8:1 1 1.1G 0 part ││ +└─sda2 8:2 1 3M 0 part ││ +nvme0n1 259:0 0 931.5G 0 disk ││ +├─nvme0n1p1 259:1 0 512M 0 part /b ││ oot ││ +└─nvme0n1p2 259:2 0 931G 0 part ││ + └─cryptroot 254:0 0 931G 0 crypt /p ││ ersist ││ +``` ││ + ││ +Here we can see that `sda` is the intended ││ target for our usb, so the full path ││ +would be `/dev/sda` ││ + ││ +#### Obtain install image ││ + ││ +Download the ││ +[Minimal NixOS Install Image](https://chann ││ els.nixos.org/nixos-24.11/latest-nixos-minim ││ al-x86_64-linux.iso). ││ + ││ +#### Flash the USB ││ + ││ +Run the following command to flash the USB ││ with the installation image: ││ ││ ```sh ││ -# what drive we are using ││ -export D="/dev/vda" ││ -export D1=$D'1' ││ -export D2=$D'2' ││ +# Assuming the iso was downloaded to ~/Down ││ loads/latest-nixos-minimal-x86-64-linux.iso ││ +$ sudo dd bs=4M if=~/Downloads/latest-nixos ││ -minimal-x86-64-linux.iso of=/dev/sda status ││ =progress && sync ││ +``` ││ ││ -# size of the swap for example 1GiB swap wo ││ uld be: ││ -export SWAP=1g ││ -sudo parted -s $D mklabel gpt mkpart "EFI" ││ fat32 1MiB 513MiB mkpart "NixOS" btrfs 513Mi ││ B 100% set 1 esp on ││ -sudo mkfs.fat -F 32 $D1 && sudo mkfs.btrfs ││ -f $D2 ││ +#### Boot into install media ││ ││ -sudo mount $D2 -m /mnt ││ +Using your host's BIOS (UEFI) boot manager, ││ boot into the installation media. ││ ││ -sudo btrfs subvolume create /mnt/root ││ -sudo btrfs subvolume create /mnt/home ││ -sudo btrfs subvolume create /mnt/nix ││ -sudo btrfs subvolume create /mnt/swap ││ +#### Disk partitioning ││ ││ -sudo umount /mnt ││ +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: ││ ││ -sudo mount -o subvol=root $D2 -m /mnt ││ -sudo mount -o subvol=home $D2 -m /mnt/home ││ -sudo mount -o subvol=nix $D2 -m /mnt/nix ││ -sudo mount -o subvol=swap $D2 -m /mnt/swap ││ -sudo mount $D1 -m /mnt/boot ││ +Use `lsblk` to determine the target disk we ││ want to partition ││ ││ -sudo btrfs filesystem mkswapfilee --size $S ││ WAP --uuid clear /mnt/swap/swapfile ││ +```sh ││ +$ lsblk ││ + ││ +NAME MAJ:MIN RM SIZE RO TYPE MO ││ UNTPOINTS ││ +sda 8:0 1 57.3G 0 disk ││ +├─sda1 8:1 1 1.1G 0 part ││ +└─sda2 8:2 1 3M 0 part ││ +nvme0n1 259:0 0 931.5G 0 disk ││ ``` ││ ││ -## Installing Nix ││ +In this case we will be using `nvme0n1` ││ ││ ```sh ││ -sudo nixos-generate-conig --root /mnt ││ -sudo nixos-install ││ -# done ││ +# if you would like to avoid using sudo rep ││ eatedly, you can opt to run sudo -i to login ││ as root. In the following example I will op ││ t not too use sudo -i ││ + ││ +# 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 SWAP=4g ││ ``` ││ + ││ +Formatting and mounting ││ + ││ +```sh ││ +# partition drive ││ +$ sudo parted \ ││ +-s $D mklabel gpt \ ││ +mkpart "EFI" fat32 1MiB 513MiB \ # boot par ││ tition ││ +mkpart "NixOS" btrfs 513MiB 100% set 1 esp ││ on # root partition ││ + ││ +$ sudo mkfs.fat -F 32 $P1 && sudo mkfs.btrf ││ s -f $P2 # define partition filesystem ││ + ││ +# mount drives to create subvolumes ││ +$ sudo mount $P2 -m /mnt ││ + ││ +# define subvolumes ││ +$ sudo btrfs subvolume create /mnt/{root,ni ││ x,home,swap} ││ + ││ +$ sudo umount /mnt ││ + ││ +# mount all subvolumes to there respective ││ paths, making the directories if needed ││ +$ sudo mount -o subvol={root,home,nix,swap} ││ $P2 -m /mnt{,/home,/nix,/swap} ││ + ││ +# mount boot ││ +$ sudo mount $P1 -m /mnt/boot ││ + ││ +# create swap file ││ +$ sudo btrfs filesystem mkswapfile --size $ ││ SWAP --uuid clear /mnt/swap/swapfile ││ +``` ││ + ││ +#### 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 ││ +configuration, with a couple modifications. ││ Then building from ooknet once ││ +installed. ││ + ││ +```sh ││ +# generate hordware-configuration.nix ││ +$ sudo nixos-generate-config --root /mnt ││ +``` ││ + ││ +Using preferred text editor, add the follow ││ ing to ││ +`/mnt/etc/nixos/configuration.nix`: ││ + ││ +```nix ││ +# setup "wheel" user ││ +users.users.ooks = { ││ + isNormalUser = true; ││ + extraGroups = ["wheel" "video" "audio"]; ││ +}; ││ +# configure 1Password module, this will be ││ used to obtain secrets to install the intend ││ ed host configuration ││ +programs = { ││ + _1password.enable = true; ││ + _1password-gui = { ││ + enable = true; ││ + polkitPolicyOwners = ["ooks"]; ││ + }; ││ +}; ││ +``` ││ + ││ +You will also need some sort of graphical e ││ nvironment to boot into, I recommend ││ +something simple like gnome ││ + ││ +```nix ││ +services.xserver = { ││ + enable = true; ││ + displayManager.gdm.enable = true; ││ + desktopManager.gnome.enable = true; ││ +}; ││ +# disable unnecessary gnome packages ││ +environment.gnome.excludePackages = with pk ││ gs; [ ││ + orca ││ + epiphany ││ + evince ││ + gedit ││ + gnome-music ││ + gnome-photos ││ + gnome-terminal ││ + gnome-tour ││ + hitori ││ + iagno ││ + tali ││ + atomix ││ +]; ││ +``` ││ + ││ +Install the system ││ + ││ +```sh ││ +$ sudo nixos-install ││ +``` ││ + ││ +Set a password for the user ││ + ││ +```sh ││ +$ sudo nixos-enter --root /mnt -c 'passwd o ││ oks' ││ +``` ││ + ││ +Reboot the system ││ + ││ +#### Post install ││ + ││ +After booting into the fresh installation y ││ ou will need to authenticate with ││ +1Password and move the ssh keys required fo ││ r secret decryption into ~/.ssh. ││ + ││ +Following that, you can run: ││ + ││ +`sudo nixos-rebuild --flake github:ooks-io/ ││ ooknet#<hostname>` │└──────────────────────────────────────────────┘