feat: add comprehensive NixOS configuration documentation and structure

- Introduced `08-structure.md` detailing project structure, main files, and versioning. - Created `README.md` for documentation overview and quick start guide. - Added user-specific configurations for Alacritty, Vim, Micro, Git, Zsh, Tmux, and tools. - Implemented system modules for desktop environment (KDE Plasma), audio (PipeWire), networking, and services (OpenSSH, GnuPG). - Configured Nix settings with flakes support and garbage collection. - Established user management for `ada` with necessary groups and shell settings. - Enabled VirtualBox guest additions for improved VM experience.
2026-03-10 13:10:52 +03:00
parent a7ba016de4
commit 17b0cdfbac
31 changed files with 3327 additions and 164 deletions
@@ -0,0 +1,285 @@
+# Отладка и решение проблем
+
+Что делать когда что-то не работает.
+
+## Конфигурация не собирается
+
+### Ошибка синтаксиса
+
+```bash
+# Проверить синтаксис
+nix flake check
+
+# Посмотреть ошибку
+nh os test
+```
+
+Читай ошибку внимательно - она указывает на строку файла.
+
+## Ошибка: пакет не найден
+
+```bash
+# Проверить существует ли пакет
+nix search nixpkgs package-name
+
+# Полное имя может быть другим
+nix search nixpkgs git-lfs
+```
+
+Если пакет не найден:
+1. Проверь имя в [https://search.nixos.org](https://search.nixos.org)
+2. Возможно пакет устарел
+3. Попробуй альтернативу
+
+## Ошибка: модуль не импортируется
+
+```bash
+# Если добавил новый модуль и он не применяется
+nix flake check
+
+# Проверить импорт в configuration.nix
+grep "./modules/mymodule" configuration.nix
+
+# Проверить путь (должен быть правильный относительный путь)
+```
+
+Старые импорты кэшируются. Попробуй:
+```bash
+rm -rf .direnv  # Если использует direnv
+nix flake update
+```
+
+## Сборка зависает
+
+Обычно при первой сборке это может быть долгим (20-30 минут).
+
+Если зависает надолго:
+```bash
+# Прервать (Ctrl+C)
+
+# Очистить кэш
+nix flake update
+
+# Пробовать снова
+nh os test
+```
+
+## Команда не работает после apply
+
+```bash
+# Обновить PATH
+exec $SHELL
+
+# Или перезагрузить terminal
+# В новом окне терминала попробуй команду
+```
+
+## SSH не работает
+
+```bash
+# Проверить статус
+sudo systemctl status ssh
+
+# Посмотреть логи
+sudo journalctl -u sshd -f
+
+# Перезагрузить
+sudo systemctl restart ssh
+
+# Проверить firewall
+sudo nftables list tables
+nmcli device show
+```
+
+## Git алиасы не работают
+
+```bash
+# Применить конфигурацию
+nh os switch
+
+# Проверить что установилась
+git config --list | grep alias
+
+# Перезагрузить shell
+exec $SHELL
+```
+
+## Пакет not found после добавления
+
+```bash
+# Пересобрать
+nh os switch
+
+# Обновить PATH если нужно
+exec $SHELL
+
+# Проверить пакет
+which package-name
+```
+
+## Система не загружается
+
+Если сломал конфигурацию и система не грузится:
+
+```bash
+# При загрузке в GRUB выбери предыдущую версию системы
+```
+
+Или откати изменения:
+```bash
+cd /home/ada/.dotfiles/nixos
+git checkout configuration.nix
+nh os switch
+```
+
+## Firewall блокирует
+
+```bash
+# Проверить статус
+sudo nftables list tables
+
+# Открыть порт (редактор файл)
+# modules/networking/default.nix
+networking.firewall.allowedTCPPorts = [ 22 8080 ];
+
+# Собрать
+nh os switch
+```
+
+## Нет интернета
+
+```bash
+# Проверить связь
+ping 8.8.8.8
+
+# Проверить DNS
+nslookup google.com
+
+# Перезагрузить NetworkManager
+sudo systemctl restart NetworkManager
+
+# Посмотреть статус
+nmcli status
+```
+
+## Логирование и отладка
+
+### Посмотреть логи системы
+
+```bash
+# Последние ошибки
+sudo journalctl -b | tail -50
+
+# Логи конкретного сервиса
+sudo journalctl -u ssh -f
+
+# По уровню важности
+sudo journalctl -p err
+```
+
+### Проверить что загрузилось
+
+```bash
+# Посмотреть текущую конфигурацию
+systemctl status
+ps aux
+
+# Проверить конкретный сервис
+systemctl status sshd
+systemctl status NetworkManager
+```
+
+## Производительность
+
+Если система медленная:
+
+```bash
+# Посмотреть процессы
+btop
+
+# Посмотреть использование диска
+du -sh ~/*
+
+# Нулевые файлы
+find / -size 0 2>/dev/null
+
+# GC собрал много?
+du -sh /nix/store
+nix store gc
+```
+
+## Вернуть рабочее состояние
+
+### Откатить последнее изменение
+
+```bash
+# В git
+git checkout HEAD -- home/ada/packages.nix
+
+# Пересобрать
+nh os switch
+```
+
+### Посмотреть историю поколений
+
+```bash
+nh os list
+
+# Откатить на предыдущее поколение
+sudo nix-env -p /nix/var/nix/profiles/system --switch-generation N
+```
+
+### Резервная копия
+
+Есть файл конфигурации до изменений:
+```
+configuration.nix.backup
+```
+
+Если что-то критичное сломалось:
+```bash
+cp configuration.nix configuration.nix.broken
+cp configuration.nix.backup configuration.nix
+nh os switch
+```
+
+## Получить помощь
+
+### Проверить логи
+
+```bash
+# Полные логи последней сборки
+nixos-rebuild dry-run 2>&1 | head -100
+```
+
+### Читать ошибки
+
+Обычно в ошибке указывается:
+1. **Файл** - какой файл конфига проблема
+2. **Строка** - на какой строке
+3. **Ошибка** - что именно не так
+
+### Поиск в документации
+
+```bash
+# Поиск опции
+nixos-option services.openssh
+
+# Поиск в nixpkgs
+nix search nixpkgs pattern
+```
+
+## Когда ничего не помогает
+
+```bash
+# 1. Откатить на рабочее состояние
+git checkout HEAD~1
+
+# 2. Собрать
+nh os switch
+
+# 3. Проверить что работает
+systemctl status
+
+# 4. Медленнее добавить изменения по одному
+```