Installation

Note

This page is not a full guide, though consider this a reference since it doesn't go through the minimal install method.

Get a graphical NixOS ISO Image

• The current NixOS release is 26.05. The graphical ISO for 64-bit Intel/AMD is at https://channels.nixos.org/nixos-26.05/latest-nixos-graphical-x86_64-linux.iso.
• To get started, either use:
  • elinks+dd in the terminal.
  • In an actual Desktop Environment, use a browser. (it's this simple.)

In Your Desktop

• You must install elinks using your package manager first, for me on Bedrock Linux, it would be something like this: brl strat void xbps-install elinks.
• Using the elinks command, visit the NixOS Download page with:

  $ elinks https://nixos.org/download/

• You'll then be in a somewhat readable interface that lets you navigate through the page with arrow keys.
• Just find the section where it says: "NixOS: the Linux distribution", you can easily search for this text by pressing /.
• On the highlighted link of your preferred architecture of the ISO image, you may press → to follow link and download.

Using the dd command

• dd is the best tool for writing/burning an ISO image into a disk, I've been using it every time I destroy my Gentoo install. (In which I'm kinda proud of?)
• Check which device you want to write the ISO image in with lsblk.
• An example of using dd, write nixos-sample.iso to /dev/sdX:

root # dd if=nixos-sample.iso of=/dev/sdX bs=4M status=progress oflag=sync

• to explain what some options do that weren't mentioned beforehand,
  • bs=4M basically tells dd to write 4MB chunks rather than the usual 512 bytes.
  • status=progress only shows progression.
  • oflag=sync synchronous output: After every write, data is flushed to the external drive.
• After it's done writing, you can now boot into the external drive.

Note

Before proceeding to boot into the media, you might not be able to boot to it at first, especially if it's your first time doing this in a new machine, and it could be that you either: forgot to set the boot order correctly, or you forgot to turn off Secure Boot.

In the Live Environment

• In the live environment, you may proceed with the installation as is.
• Optional 'requirements':
  • Use BTRFS as the root filesystem.
  • Set GNOME as the Desktop Environment on install.
  • Set username as alice.
• Here's a table of my good ol' partitions:

Partition	Filesystem	Mountpoint	Size
/dev/sda1	FAT32	/boot	1024MiB
/dev/sda2	linuxswap	N/A	1.5 * RAM in my usual case.
/dev/sda3	BTRFS	/	The rest of the disk space.

• Please take a look at this page if you don't know how to make a space for swap: What about swap space?
• Making BTRFS subvolumes for root is pointless as the installer actually handles that automatically.
• Reboot to the newly NixOS install afterwards, you can do so after a while of waiting for the installer to finish. Check the box right beside "Reboot Now" and press OK.

Warning

A portion of the code within Alice is hardcoded to /home/alice. If you use a different username on install, change these files:

• modules/hosts/serpentine/settings/user.nix (home directory)
• modules/hosts/serpentine/settings/programs.nix (the nh flake path)
• modules/home/alice/core.nix (home directory)
• modules/home/alice/cursor.nix (cursor target directory)
• modules/home/alice/desktop/dms.nix (configHome)

If you think you did something wrong during install, you can cancel and get back at it.

Within the new NixOS machine

• You're finally within the operating system, but you're still not done yet. The procedure will be more straightforward though.
• In a terminal (GNOME Console, if you chose GNOME), nano is the only reliable text editor you can use. So, in this case, either use nix-shell to install Vim/Neovim temporarily:

  user $ nix-shell -p vim # Feel free to replace this with your preferred editor.

• OR just use nano for an immediate act, use sudo -i if you're going to be moving back and forth to configuration.nix multiple times, it saves a bit of time than to type your password every time:

  user $ sudo -i
  root # nano /etc/nixos/configuration.nix
  

Configuring the file temporarily

• In configuration.nix, we will need to add a few lines:

  {
    nix = {
      settings = {
        experimental-features = [
          "nix-command"
          "flakes"
        ];
        substituters = [
          "https://attic.xuyh0120.win/lantian"
        ];
        trusted-public-keys = [
          "lantian:EeAUQ+W+6r7EtwnmYjeVwx5kOGEBpjlBfPlzGlTNvHc="
          "noctalia.cachix.org-1:pCOR47nnMEo5thcxNDtzWpOxNFQsBRglJzxWPp3dkU4="
        ];
      };
    };
    
  	# This is non-mandatory, you can ignore this line.
    # Although if you want to follow through this, 
    # make sure you remove networking.networkmanager.enable = true;
    # Somewhere in the configuration.nix.
  	networking = {
  	  hostName = "nixos"; # Change hostname to your liking~
  	  networkmanager = {
  	    enable = true;
  	    wifi.macAddress = "random";
  	  };
  	};
  }

• Enabling flakes lets the nix command use flake.nix. This is mandatory. The lantian substituter is the binary cache of the CachyOS kernel (nix-cachyos-kernel), which Serpentine uses. With it, you don't compile the kernel yourself. Adding only "nix-command" and "flakes" is completely fine, but then the kernel builds from source.
• To clone alice, we need to have git installed in our system. Either use nix-shell -p git or add git to the environment.systemPackages block:

  {
    environment.systemPackages = with pkgs; [
    # vim
    wget
    git # <- We're going to use this for cloning Alice.
    ];
  }

• After you're done editing configuration.nix, you can now rebuild your system:

  root # nixos-rebuild switch
  

• But why rebuild now? Nix settings configured just now are not applied to the system yet; they still need to be rebuilt.
• You may choose to use the --offline flag for this rebuild.

Using Alice

• You will need to clone the Alice repository with git. test-den is the working branch, so clone that one. I recommend cloning the repository to $HOME/.local/share/alice as it doesn't clutter your home directory. Unlike mine. :(

user $ git clone -b test-den --single-branch https://github.com/hxrmonlka/alice.git

• Again, if you decide to use nix-shell to temporarily use git:

user $ nix-shell -p git
[nix-shell:~/.local/share/alice]$ git clone ...

• Serpentine sets programs.nh.flake = "/home/alice/alice". The command nh os switch without arguments looks in that path. Clone Alice to /home/alice/alice, or change that line in modules/hosts/serpentine/settings/programs.nix.

Using a different hardware config

• Alice doesn't automatically fetch your hardware-configuration.nix within /etc/nixos/ or something like that, you will need to add your hardware-configuration.nix somewhere in ./modules/hardware/profiles. That directory holds the profiles that exist now: a15.nix, noct.nix and qemu.nix.
• A good way of copying the whole hardware-configuration.nix file is to first, remove the comments at the very top, assuming it's only three lines, you can check it out:

user $ cat /etc/nixos/hardware-configuration.nix | head -n 3
# Do not modify this file!  It was generated by ‘nixos-generate-config’
# and may be overwritten by future invocations.  Please make changes
# to /etc/nixos/configuration.nix instead.

• Remove it with nano or with your preferred editor:

root # nano /etc/nixos/hardware-configuration.nix

• Alternatively, you can use sed to the three lines we just saw earlier if it is available in your environment:

root # sed -i '1,3d' /etc/nixos/hardware-configuration.nix

• You then copy the output of cat using wl-clipboard from nixpkgs, you'll either install it through systemPackages or nix-shell.

user $ nix-shell -p wl-clipboard
[nix-shell:~]$ cat /etc/nixos/hardware-configuration.nix | wl-copy
[nix-shell:~]$ # Within $HOME/.local/share/alice
[nix-shell:~]$ cd .local/share/alice
[nix-shell:~/.local/share/alice]$ wl-paste > modules/hardware/profiles/my-hardware-config.nix

• And there you have it, you've finally added your hardware config to Alice.

Following the Dendritic Pattern

• Alice wires each hardware profile as a module in flake.custom.hardwareModules. Follow that, as noct.nix does.
• It is clearer to copy the text inside my-hardware-config.nix, and then make a new one.
• Copy your hardware config file, this command assumes you're still at $HOME/.local/share/alice:

user $ cat modules/hardware/profiles/my-hardware-config.nix | wl-copy

• The next step is to use what you've copied into a new file. Put the header lines first, paste your hardware config after the = sign, and end the file with a semicolon and a closing brace.
• It should look something like this:

{ self, inputs, ... }: {
  flake.custom.hardwareModules.myHardwareConfig = { config, lib, pkgs, modulesPath, ... }: {
    imports = [
      (modulesPath + "/installer/scan/not-detected.nix")
    ];

    boot.initrd.availableKernelModules = [ "ahci" "sd_mod" "sr_mod" ];
    boot.initrd.kernelModules = [];
    boot.kernelModules = [];
    boot.extraModulePackages = [];
  };
}

• Your own file has more lines (file systems, swap, microcode). The structure stays the same. Do not forget the semicolon after the closing brace of your pasted module.
• You'll notice that it looks very off in terms of readability. But that's okay, it can be fixed by Neovim later.
• For now, we plan on wiring this module into a host. In this case, a good example would be serpentine, within ./modules/hosts/serpentine, you'll find its configuration.nix file. Open it.
• From there, you'd want to first remove the other hardware profile it uses and add the one you created:

      self.custom.hardwareModules.intelSettings
-     self.custom.hardwareModules.noctHardware
+     self.custom.hardwareModules.myHardwareConfig
      self.custom.hardwareModules.otdSettings

• If you do not want to change Serpentine, make a new host. See Hosts.

Using a driver within modules/hardware/drivers

• In your preferred host, you can use a different driver in which is absolutely customizable. These modules are:
  • flake.*
    • custom.hardwareModules.*
      • hardwareAmd
      • hardwareIntel
      • hardwareNvidia
      • vulkan
    • nixosModules.*
      • hardwareFramework
• These are wired into configuration.nix or default.nix, within a host. Serpentine uses Intel, for example. The legacy profile is used, to configure it, go to modules/hardware/settings/. See Intel, AMD and Nvidia for the options.
• After making changes, you may stage your changes with git add . before nh os switch, take a look at the project to see what it does: nh.
• home-manager is wired into configuration.nix, and it is installed as a NixOS module, so the system rebuild also applies your home configuration. On the first build, your hostname is still the one from the installer, so name the host: nh os switch .#serpentine. Yes, you can use nix-shell for this temporarily. After that first build, the hostname is serpentine and plain nh os switch works. Right after that, you're pretty much good to go.

Tip

Did you forget to remove the old my-hardware-config.nix? Make sure to do nh clean all / nix-collect-garbage -d right after building Alice!

Testing in a VM

• If you want to test a host before you install it, use the dev shell in the repository:

user $ nix develop
user $ build-vm serpentine

• build-vm <host> builds the host as a QEMU VM and starts it. Without a host name, it lists the available hosts.