Understanding Kaku: A NixOS Configuration Guide

Overview

This guide explains my personal NixOS configuration, Kaku, designed for a modern desktop environment. Before diving in, you can preview the configuration structure using:

› nix flake show github:linuxmobile/kaku
github:linuxmobile/kaku/8394cdcfd946c9620d202fec46f5eb625812c826
├───devShells
│   └───x86_64-linux
│       └───default: development environment 'nixland'
├───formatter
│   └───x86_64-linux: package 'alejandra-3.0.0'
├───homeConfiguration: unknown
├───nixosConfigurations
│   └───aesthetic: NixOS configuration
├───nixosModules
│   └───theme: NixOS module
└───packages
    └───x86_64-linux
        ├───biome: package 'biome-1.5.3'
        ├───repl: package 'repl'
        └───wezterm: package 'wezterm-unstable-e3cd2e93d0ee5f3af7f3fe0af86ffad0cf8c7ea8'

Configuration Structure

The configuration is organized into six main directories, each with a specific purpose:

1. Directory Layout

├── home
│   ├── editors
│   ├── profiles
│   ├── services
│   ├── software
│   ├── terminal
│   ├── default.nix
│   └── specialization.nix
├── hosts
│   ├── aesthetic
│   └── default.nix
├── lib
│   ├── theme
│   ├── default.nix
│   └── repl.nix
├── modules
│   ├── theme
│   └── default.nix
├── pkgs
│   ├── biome
│   ├── repl
│   ├── wezterm
│   └── default.nix
├── system
│   ├── core
│   ├── hardware
│   ├── network
│   ├── nix
│   ├── programs
│   ├── services
│   └── default.nix
├── .envrc
├── flake.lock
└── flake.nix

2. Home Directory (`home/`)

The home/ directory manages user-specific configurations using Home Manager:

Home

| Name                | Description                                             |
| ------------------- | ------------------------------------------------------- |
| default.nix         | Special Home-Manager configuration                      |
| editors             | Helix & VSCode                                          |
| profiles            | Device profiles, configuration entry point              |
| programs            | Programs, media, etc.                                   |
| services            | Services like ags, etc                                  |
| terminal            | Terminal programs, shells, etc                          |
| specialisations.nix | Special Light/Dark configuration                        |

Editors: Logically contains the text editors you need.
Profiles: It’s recommended to create your own profile and add it to default.nix. Later you’ll link it to the Host configuration.
Programs/Software: This section contains general software.
Services: Logically contains services or programs that act as services.
Terminal: Zsh, CLI tools and more.

💡 Tip: Create your profile in profiles/ and link it to your host configuration.

3. Host Configuration (`hosts/`)

Each machine gets its own configuration:

| Name      | Description                    |
| --------- | ------------------------------ |
| aesthetic | LinuDev's Main Computer        |

All hosts share common settings through modules/core.nix, with machine-specific configurations in their respective directories.

4. Custom Libraries (`lib/`)

Contains utility functions and theme management:

| Name        | Description                                  |
| ----------- | -------------------------------------------- |
| colors      | Function to handle system colors             |
| default.nix | Module for flake-parts                       |
| repl.nix    | Cool Nix REPL wrapper                        |
| theme       | Program that I reference later               |

5. Custom Packages (`pkgs/`)

Self-maintained packages:

| Name    | Description                                          |
| ------- | ---------------------------------------------------- |
| biome   | Biome.js, nixpkgs updates too slowly                 |
| repl    | auto-loads system flake in current dir               |
| wezterm | There was a Wayland issue, I fix it here             |

6. System Configuration (`system/`)

Core system settings:

| Name     | Description              |
| -------- | ------------------------ |
| Core     | Shared configuration     |
| Hardware | Hardware config          |
| Network  | Network config           |
| Nix      | Nix-related              |
| Programs | System software          |
| Services | System services          |

In core we find the user configuration, boot configuration (shared across all PCs)
In hardware you can change GPU drivers
In network you’ll find network-related settings
In nix contains configuration for nh, nixpkgs and more
In programs contains system fonts, home-manager, xdg and more
In services contains system services, localization, pipewire, etc.

Highly recommended: review each folder and see what is necessary and what isn’t.

Fresh Installation Guide

Prerequisites

A USB drive with NixOS
UEFI-capable system
Basic command line knowledge

Step-by-Step Installation

Partition the Disk

Create three partitions using gdisk:
- EFI (512MB)
- Root (50GB+)
- Home (remaining space)
Terminal window
```
gdisk /dev/nvme0n1
# 'o' - create new partition table
# 'n' - new partition (EFI: type ef00)
```

Format Partitions

# Format EFI partition
mkfs.fat -F 32 /dev/nvme0n1p1

# Format root partition (XFS)
mkfs.xfs /dev/nvme0n1p2

# Format home partition
mkfs.xfs /dev/nvme0n1p3

Mount Filesystems

mount /dev/disk/by-label/NIXOS /mnt
mkdir -p /mnt/boot
mount /dev/disk/by-label/EFI /mnt/boot

Enable Required Tools
Terminal window
```
nix-shell -p nixFlakes git
```

Clone Configuration

git clone --depth 1 https://github.com/linuxmobile/kaku /mnt/etc/nixos

Generate Hardware Configuration

sudo nixos-generate-config --dir --force /mnt/etc/nixos/hosts/aesthetic

Install System

cd /mnt/etc/nixos
nixos-install --flake .#aesthetic

Post-Installation

After installation:

Review the configuration files
Customize user settings
Rebuild the system to apply changes

Troubleshooting

If you encounter issues:

Verify all partitions are mounted correctly
Check the hardware configuration
Ensure flake.nix is properly configured

NixOS Installation & Configuration Guide