dotfiles/nixos/docs/08-structure.md

Структура проекта

Как устроена конфигурация.

Главные файлы

flake.nix               - Главная входная точка
configuration.nix       - Системная конфигурация

Папки

modules/                - Системные модули
home/ada/               - Конфигурация пользователя (Home Manager)
docs/                   - Документация (этот гайд)

Версионирование

flake.nix

inputs = {
  # Откуда берёмся пакеты
  nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";

  # Управление пользовательским окружением
  home-manager.url = "github:nix-community/home-manager/release-25.11";
};

• NixOS версия: 25.11 (стабильный релиз)
• Home Manager версия: 25.11 (синхронизирована)

Системные модули

modules/system/

Ядро системы:

• boot.nix - GRUB загрузчик, kernel modules
• nix.nix - Nix конфигурация (flakes, gc, substituters)
• locale.nix - Таймзона (Europe/Moscow), системные locale

modules/desktop/

Рабочее окружение:

• plasma.nix - KDE Plasma 6, Wayland, X11, раскладка клавиатуры
• pipewire.nix - Audio система (PipeWire + ALSA)

modules/networking/

Сетевые сервисы:

• default.nix - NetworkManager, Firewall

modules/services/

Системные сервисы:

• default.nix - SSH (hardened), Firefox, GnuPG, VPN support

modules/users/

Управление пользователями:

• ada.nix - Пользователь ada (groups, shell: zsh)

modules/virtualisation/

Виртуализация:

• virtualbox.nix - VirtualBox Guest Additions (drag&drop, clipboard)
• qemu-guest.nix - QEMU/KVM Guest поддержка (spice-vdagent)

Home Manager (Пользователь ada)

home/ada/default.nix

Главный файл (импорты всех модулей):

home.username = "ada";
home.homeDirectory = "/home/ada";
home.stateVersion = "25.05";

Модули пользователя

Файл	Назначение
packages.nix	50+ пакетов (организованы по категориям)
alacritty.nix	Терминальный эмулятор (Nord тема, FiraCode)
vim.nix	Vim редактор (Nord тема, плагины)
micro.nix	Micro редактор (простой редактор)
git.nix	Git конфигурация (15+ алиасов, colors)
zsh.nix	ZSH shell (30+ алиасов, интеграции)
tmux.nix	Tmux терминальный мультиплексер (VI mode)
tools.nix	CLI утилиты (bat, fzf, direnv)

Информационный поток

flake.nix (входная точка)
    ↓
    ├─→ nixpkgs (версия 25.11)
    ├─→ home-manager (версия 25.11)
    └─→ nixos-hardware

configuration.nix (система)
    ├─→ hardware-configuration.nix
    ├─→ modules/system/* (boot, nix, locale)
    ├─→ modules/desktop/* (plasma, pipewire)
    ├─→ modules/networking/* (network)
    ├─→ modules/services/* (ssh, firefox, etc.)
    ├─→ modules/users/* (пользователь)
    ├─→ modules/virtualisation/* (vbox)
    └─→ Home Manager (через special args)

home/ada/default.nix (пользователь)
    ├─→ packages.nix (50+ пакетов)
    ├─→ alacritty.nix (терминал)
    ├─→ vim.nix (editor)
    ├─→ micro.nix (editor)
    ├─→ git.nix (git config)
    ├─→ zsh.nix (shell)
    ├─→ tmux.nix (multiplexer)
    └─→ tools.nix (utilities)

Категории пакетов

В packages.nix пакеты организованы так:

Редакторы        vim, neovim, micro
IDE              vscode, idea-community, zed
Терминал         alacritty
Dev tools        tmux, fzf, ripgrep, fd, bat, eza...
Git              git, gh, lazygit
Сеть             curl, wget, ssh, mosh, nmap...
БД               sqlite, postgresql
Утилиты          jq, yq, zip, unzip, gnupg...
Шрифты           nerdfonts (FiraCode)

Какой файл менять?

Задача	Файл
Добавить переменную окружения	home/ada/zsh.nix
Добавить программу	home/ada/packages.nix
Изменить Git конфиг	home/ada/git.nix
Добавить Shell alias	home/ada/zsh.nix
Настроить SSH	modules/services/default.nix
Открыть firewall порт	modules/networking/default.nix
Добавить язык/locale	modules/system/locale.nix
Установить новый сервис	Создать новый модуль в modules/
Конфигурировать программу	Создать новый модуль в home/ada/

Версия конфигурации

# configuration.nix
system.stateVersion = "25.05";

# home/ada/default.nix
home.stateVersion = "25.05";

# Обновить можно когда готов к миграции
# Но ОСТОРОЖНО - читай документацию NixOS

Как это всё работает?

1. flake.nix - говорит Nix где брать пакеты и как их собрать
2. configuration.nix - импортирует все системные модули
3. modules/ - каждый модуль отвечает за часть системы
4. home/ada/default.nix - импортирует все пользовательские модули
5. home/ada/ - каждый модуль конфигурирует программу

Когда ты делаешь nh os switch:

1. Нужно собрать конфигурацию
2. Nix читает flake.nix
3. Понимает что использовать из inputs (nixpkgs, home-manager)
4. Собирает configuration.nix (импортирует все modules/)
5. Собирает home/ada/default.nix через Home Manager
6. Создаёт результат (нов поколение системы)
7. Переключается на него

Быстрая справка

# Посмотреть версию
cat configuration.nix | grep stateVersion

# Посмотреть импорты
head -30 configuration.nix

# Список всех модулей
ls -la modules/**/*.nix

# Список Home Manager модулей
ls -la home/ada/*.nix

# Найти файл по названию
find . -name "*ssh*"

Следующие шаги

Если хочешь что-то изменить:

1. Найди нужный файл (выше таблица)
2. Отредактируй его
3. Собери: nh os switch
4. Если не работает → см. docs/07-troubleshooting.md