From 8cf97d2a0cf76adcc305ca8a50143bca2eed691c Mon Sep 17 00:00:00 2001
From: yunfachi <yunfachi@gmail.com>
Date: Thu, 3 Oct 2024 17:49:27 +0300
Subject: [PATCH] docs/src/getting_started/initialization: init

---
 docs/.vitepress/config.mts                    |  10 +-
 docs/src/getting_started/initialization.md    | 306 ++++++++++++++++++
 docs/src/ru/getting_started/initialization.md | 306 ++++++++++++++++++
 3 files changed, 620 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/getting_started/initialization.md
 create mode 100644 docs/src/ru/getting_started/initialization.md

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 91b1342..6cb62a5 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -48,7 +48,10 @@ function themeConfigEnglish() {return {
     sidebar: [
       {
         text: "Getting Started",
-        items: [{ text: "Introduction", link: "/getting_started/introduction" }],
+        items: [
+          { text: "Introduction", link: "/getting_started/introduction" },
+          { text: "Initialization", link: "/getting_started/initialization" },
+        ],
       },
       {
         text: "Modules",
@@ -114,7 +117,10 @@ function themeConfigRussian() {return {
     sidebar: [
       {
         text: "Начнем",
-        items: [{ text: "Вступление", link: "/ru/getting_started/introduction" }],
+        items: [
+          { text: "Вступление", link: "/ru/getting_started/introduction" },
+          { text: "Инициализация", link: "/ru/getting_started/initialization" },
+        ],
       },
       {
         text: "Модули",
diff --git a/docs/src/getting_started/initialization.md b/docs/src/getting_started/initialization.md
new file mode 100644
index 0000000..65a8ba5
--- /dev/null
+++ b/docs/src/getting_started/initialization.md
@@ -0,0 +1,306 @@
+# Configuration Initialization
+This section will describe creating the `minimal` template from scratch.
+
+You do not have to do this; you can simply clone the minimal configuration template with the following command:
+```sh
+nix flake init -t github:yunfachi/denix#minimal
+```
+
+You can also copy the minimal configuration template without the rices:
+```sh
+nix flake init -t github:yunfachi/denix#minimal-no-rices
+```
+
+## Flake
+First, create a directory for your configuration and a `flake.nix` file with the following content:
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    home-manager = {
+      url = "github:nix-community/home-manager/master";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+    denix = {
+      url = "github:yunfachi/denix";
+      inputs.nixpkgs.follows = "nixpkgs";
+      inputs.home-manager.follows = "home-manager";
+    };
+  };
+  
+  outputs = {
+    denix,
+    nixpkgs,
+    ...
+  } @ inputs: let
+    mkConfigurations = isHomeManager:
+      denix.lib.configurations {
+        homeManagerNixpkgs = nixpkgs;
+        homeManagerUser = "sjohn"; #!!! REPLACEME
+        inherit isHomeManager;
+
+        paths = [./hosts ./modules ./rices];
+
+        specialArgs = {
+          inherit inputs;
+        };
+      };
+  in {
+    nixosConfigurations = mkConfigurations false;
+    homeConfigurations = mkConfigurations true;
+  };
+}
+```
+
+If you are not familiar with `inputs` and `outputs`, read [NixOS Wiki Flakes](https://nixos.wiki/wiki/Flakes).
+
+Code explanation:
+- `mkConfigurations` - a function to reduce code repetition, which takes `isHomeManager` and passes it to `denix.lib.configurations`.
+- `denix.lib.configurations` - [Configurations (flakes) - Introduction](/configurations/introduction).
+- `paths = [./hosts ./modules ./rices];` - paths to be recursively imported by Denix. Remove `./rices` if you don't want to use rices.
+
+## Hosts
+Create a `hosts` directory, and within it, create a subdirectory with the name of your host, for example, `desktop`.
+
+In this subdirectory, create a `default.nix` file with the following content:
+```nix
+{delib, ...}:
+delib.host {
+  name = "desktop"; #!!! REPLACEME
+}
+```
+
+In the same directory, create a `hardware.nix` file:
+```nix
+{delib, ...}:
+delib.host {
+  name = "desktop"; #!!! REPLACEME
+
+  homeManagerSystem = "x86_64-linux"; #!!! REPLACEME
+  home.home.stateVersion = "24.05"; #!!! REPLACEME
+
+  nixos = {
+    nixpkgs.hostPlatform = "x86_64-linux"; #!!! REPLACEME
+    system.stateVersion = "24.05"; #!!! REPLACEME
+
+    # nixos-generate-config --show-hardware-config
+    # other generated code here...
+  };
+}
+```
+
+The `default.nix` file will be modified later after adding modules and rices, so you can keep it open.
+
+## Rices
+Skip this section if you do not wish to use rices.
+
+Create a `rices` directory, and within it, create a subdirectory with the name of your rice, for example, `dark`.
+
+In this subdirectory, create a `default.nix` file with the following content:
+```nix
+{delib, ...}:
+delib.rice {
+  name = "dark"; #!!! REPLACEME
+}
+```
+
+## Modules
+Create a `modules` directory, and within it, create a `config` subdirectory (typically, it contains modules that are not tied to a specific program or service).
+
+It should be mentioned that modules represent your configuration, meaning it's up to your imagination, and you are free to change the modules as you wish.
+
+### Constants {#modules-constants}
+In this subdirectory, create a `constants.nix` file with the following content:
+```nix
+{delib, ...}:
+delib.module {
+  name = "constants";
+
+  options.constants = with delib; {
+    username = readOnly (strOption "sjohn"); #!!! REPLACEME
+    userfullname = readOnly (strOption "John Smith"); #!!! REPLACEME
+    useremail = readOnly (strOption "johnsmith@example.com"); #!!! REPLACEME
+  };
+}
+```
+
+This file is optional, as are any of its options, which are only used by you, but it is strongly recommended as good practice.
+
+### Hosts
+Also, create a `hosts.nix` file in this same directory (`modules/config`), and write any example from [Hosts - Examples](/hosts/examples).
+
+For example, we will take ["With the `type` Option"](/hosts/examples#type-option):
+```nix
+{delib, ...}:
+delib.module {
+  name = "hosts";
+
+  options = with delib; let
+    host = {config, ...}: {
+      options =
+        hostSubmoduleOptions
+        // {
+          type = noDefault (enumOption ["desktop" "server"] null);
+
+          isDesktop = boolOption (config.type == "desktop");
+          isServer = boolOption (config.type == "server");
+        };
+    };
+  in {
+    host = hostOption host;
+    hosts = hostsOption host;
+  };
+
+  home.always = {myconfig, ...}: {
+    assertions = delib.hostNamesAssertions myconfig.hosts;
+  };
+}
+```
+
+If you added an example with new options (`type`, `displays`, etc.) or made your own options, don't forget to add values for these options in the hosts.
+
+In our example, we added the `type` option, so open the `default.nix` file in your host's directory and add the attribute `type` to the `delib.host` function:
+```nix
+{delib, ...}:
+delib.host {
+  name = "desktop"; #!!! REPLACEME
+
+  type = "desktop" #!!! REPLACEME (desktop/server)
+
+  # ...
+}
+```
+
+### Rices
+Skip this section if you are not using rices.
+
+In the `modules/config` directory, create a `rices.nix` file, and write any example from [Rices - Examples](/rices/examples).
+
+For example, we will take ["Minimally Recommended Rice Module"](/rices/examples#minimally-recommended):
+```nix
+delib.module {
+  name = "rices";
+
+  options = with delib; let
+    rice = {
+      options = riceSubmoduleOptions;
+    };
+  in {
+    rice = riceOption rice;
+    rices = ricesOption rice;
+  };
+
+  home.always = {myconfig, ...}: {
+    assertions = delib.riceNamesAssertions myconfig.rices;
+  };
+}
+```
+
+Also, open the `default.nix` file of your host and add the attribute `rice` to the `delib.host` function:
+```nix
+{delib, ...}:
+delib.host {
+  name = "desktop"; #!!! REPLACEME
+
+  rice = "dark" #!!! REPLACEME
+
+  # ...
+}
+```
+
+### Home Manager
+If you created a [constants module](#modules-constants), just create a `home.nix` file with the following content:
+```nix
+{delib, ...}:
+delib.module {
+  name = "home";
+
+  home.always = {myconfig, ...}: let
+    inherit (myconfig.constants) username;
+  in {
+    home = {
+      inherit username;
+      homeDirectory = "/home/${username}";
+    };
+  };
+}
+```
+
+If you did not use the [constants module](#modules-constants), the content of the file will be:
+```nix
+{delib, ...}:
+delib.module {
+  name = "home";
+
+  home.always.home = {
+    username = "sjohn"; #!!! REPLACEME
+    homeDirectory = "/home/sjohn"; #!!! REPLACEME
+  };
+}
+```
+
+### User
+You can also create a `user.nix` file with the configuration of your NixOS user:
+```nix
+{delib, ...}:
+delib.module {
+  name = "user";
+
+  nixos.always = {myconfig, ...}: let
+    inherit (myconfig.constants) username;
+  in {
+    users = {
+      groups.${username} = {};
+
+      users.${username} = {
+        isNormalUser = true;
+        initialPassword = username;
+        extraGroups = ["wheel"];
+      };
+    };
+  };
+}
+```
+
+If you did not use the [constants module](#modules-constants), the content of the file will be:
+```nix
+{delib, ...}:
+delib.module {
+  name = "user";
+
+  nixos.always.users = {
+    groups.sjohn = {}; #!!! REPLACEME
+
+    users.sjohn = { #!!! REPLACEME
+      isNormalUser = true;
+      initialPassword = "sjohn"; #!!! REPLACEME
+      extraGroups = ["wheel"];
+    };
+  };
+}
+```
+
+## Conclusion
+If you have followed the instructions precisely, you will end up with the following configuration directory tree:
+```plaintext
+hosts
+- desktop
+  - default.nix
+  - hardware.nix
+modules
+- config
+  - constants.nix
+  - home.nix
+  - hosts.nix
+  - rices.nix
+  - user.nix
+rices
+- dark
+  - default.nix
+flake.nix
+```
+
+You can check if everything is set up correctly using the command:
+```sh
+nix flake check .#
+```
diff --git a/docs/src/ru/getting_started/initialization.md b/docs/src/ru/getting_started/initialization.md
new file mode 100644
index 0000000..cba3065
--- /dev/null
+++ b/docs/src/ru/getting_started/initialization.md
@@ -0,0 +1,306 @@
+# Инициализация конфигурации
+В этом разделе будет описано создание шаблона `minimal` с нуля. 
+
+Делать это необязательно, можно просто склонировать шаблон минимальной конфигурации с помощью команды:
+```sh
+nix flake init -t github:yunfachi/denix#minimal
+```
+
+Также можно скопировать шаблон минимальной конфигурации, но без райсов:
+```sh
+nix flake init -t github:yunfachi/denix#minimal-no-rices
+```
+
+## Флейк
+Первым делом создайте директорию под вашу конфигурацию и файл `flake.nix` со следующим содержанием:
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    home-manager = {
+      url = "github:nix-community/home-manager/master";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+    denix = {
+      url = "github:yunfachi/denix";
+      inputs.nixpkgs.follows = "nixpkgs";
+      inputs.home-manager.follows = "home-manager";
+    };
+  };
+  
+  outputs = {
+    denix,
+    nixpkgs,
+    ...
+  } @ inputs: let
+    mkConfigurations = isHomeManager:
+      denix.lib.configurations {
+        homeManagerNixpkgs = nixpkgs;
+        homeManagerUser = "sjohn"; #!!! REPLACEME
+        inherit isHomeManager;
+
+        paths = [./hosts ./modules ./rices];
+
+        specialArgs = {
+          inherit inputs;
+        };
+      };
+  in {
+    nixosConfigurations = mkConfigurations false;
+    homeConfigurations = mkConfigurations true;
+  };
+}
+```
+
+Если вы не знаете про `inputs` и `outputs`, то прочитайте [NixOS Wiki Flakes](https://nixos.wiki/wiki/Flakes).
+
+Объяснение кода:
+- `mkConfigurations` - функция для сокращения кода, которая принимает `isHomeManager` и передает его в `denix.lib.configurations`.
+- `denix.lib.configurations` - [Конфигурации (флейки) - Вступление](/ru/configurations/introduction).
+- `paths = [./hosts ./modules ./rices];` - пути, которые будут рекурсивно импортированы Denix. Удалите `./rices`, если не хотите использовать райсы.
+
+## Хосты
+Создайте директорию `hosts`, а в ней поддиректорию с названием вашего хоста, например, `desktop`.
+
+В этой поддиректории создайте файл `default.nix` со следующим содержанием:
+```nix
+{delib, ...}:
+delib.host {
+  name = "desktop"; #!!! REPLACEME
+}
+```
+
+В этой же директории создайте файл `hardware.nix`:
+```nix
+{delib, ...}:
+delib.host {
+  name = "desktop"; #!!! REPLACEME
+
+  homeManagerSystem = "x86_64-linux"; #!!! REPLACEME
+  home.home.stateVersion = "24.05"; #!!! REPLACEME
+
+  nixos = {
+    nixpkgs.hostPlatform = "x86_64-linux"; #!!! REPLACEME
+    system.stateVersion = "24.05"; #!!! REPLACEME
+
+    # nixos-generate-config --show-hardware-config
+    # остальной сгенерированный код здесь...
+  };
+}
+```
+
+Файл `default.nix` ещё будет изменяться после добавления модулей и райсов, поэтому его можно не закрывать.
+
+## Райсы
+Пропустите этот пункт, если не хотите использовать райсы.
+
+Создайте директорию `rices`, а в ней поддиректорию с названием вашего райса, например, `dark`.
+
+В этой поддиректории создайте файл `default.nix` со следующим содержанием:
+```nix
+{delib, ...}:
+delib.rice {
+  name = "dark"; #!!! REPLACEME
+}
+```
+
+## Модули
+Создайте директорию `modules`, а в ней поддиректорию `config` (обычно в ней находятся модули, которые не привязаны к какой-то программе или сервису).
+
+Стоит упомянуть, что модули - это ваша конфигурация, а значит ваша фантазия, поэтому вы вольны менять модули так, как вам угодно.
+
+### Константы {#modules-constants}
+В этой поддиректории создайте файл `constants.nix` со следующим содержанием:
+```nix
+{delib, ...}:
+delib.module {
+  name = "constants";
+
+  options.constants = with delib; {
+    username = readOnly (strOption "sjohn"); #!!! REPLACEME
+    userfullname = readOnly (strOption "John Smith"); #!!! REPLACEME
+    useremail = readOnly (strOption "johnsmith@example.com"); #!!! REPLACEME
+  };
+}
+```
+
+Этот файл необязателен, так же как и любая из его опций, которые используются лишь вами, но он настоятельно рекомендуется как хорошая практика.
+
+### Хосты
+Также создайте файл `hosts.nix` в этой же директории (`modules/config`), а в него запишите любой пример из [Хосты - Примеры](/ru/hosts/examples).
+
+Для примера мы возьмём ["С опцией `type`"](/ru/hosts/examples#type-option):
+```nix
+{delib, ...}:
+delib.module {
+  name = "hosts";
+
+  options = with delib; let
+    host = {config, ...}: {
+      options =
+        hostSubmoduleOptions
+        // {
+          type = noDefault (enumOption ["desktop" "server"] null);
+
+          isDesktop = boolOption (config.type == "desktop");
+          isServer = boolOption (config.type == "server");
+        };
+    };
+  in {
+    host = hostOption host;
+    hosts = hostsOption host;
+  };
+
+  home.always = {myconfig, ...}: {
+    assertions = delib.hostNamesAssertions myconfig.hosts;
+  };
+}
+```
+
+Если вы добавили пример с новыми опциями (`type`, `displays` и т.д.) или сами сделали свои опции, то не забудьте добавить значения этим опциям в самих хостах.
+
+В нашем примере мы добавили опцию `type`, поэтому откройте файл `default.nix` в директории вашего хоста и в функцию `delib.host` добавляем атрибут `type`:
+```nix
+{delib, ...}:
+delib.host {
+  name = "desktop"; #!!! REPLACEME
+
+  type = "desktop" #!!! REPLACEME (desktop/server)
+
+  # ...
+}
+```
+
+### Райсы
+Пропустите этой пункт, если вы не используете райсы.
+
+В директории `modules/config` создайте файл `rices.nix`, а в него запишите любой пример из [Райсы - Примеры](/ru/rices/examples).
+
+Для примера возьмём ["Минимально рекомендуемый модуль райсов"](/ru/rices/examples#minimally-recommended):
+```nix
+delib.module {
+  name = "rices";
+
+  options = with delib; let
+    rice = {
+      options = riceSubmoduleOptions;
+    };
+  in {
+    rice = riceOption rice;
+    rices = ricesOption rice;
+  };
+
+  home.always = {myconfig, ...}: {
+    assertions = delib.riceNamesAssertions myconfig.rices;
+  };
+}
+```
+
+Также откройте файл `default.nix` вашего хоста и добавьте в функцию `delib.host` атрибут `rice`:
+```nix
+{delib, ...}:
+delib.host {
+  name = "desktop"; #!!! REPLACEME
+
+  rice = "dark" #!!! REPLACEME
+
+  # ...
+}
+```
+
+### Home Manager
+Если вы создали [модуль констант](#modules-constants), то просто создайте файл `home.nix` с таким содержанием:
+```nix
+{delib, ...}:
+delib.module {
+  name = "home";
+
+  home.always = {myconfig, ...}: let
+    inherit (myconfig.constants) username;
+  in {
+    home = {
+      inherit username;
+      homeDirectory = "/home/${username}";
+    };
+  };
+}
+```
+
+Если вы не использовали [модуль констант](#modules-constants), то содержание файла будет таким:
+```nix
+{delib, ...}:
+delib.module {
+  name = "home";
+
+  home.always.home = {
+    username = "sjohn"; #!!! REPLACEME
+    homeDirectory = "/home/sjohn"; #!!! REPLACEME
+  };
+}
+```
+
+### Пользователь
+Также можно создать файл `user.nix` с конфигурацией вашего пользователя NixOS:
+```nix
+{delib, ...}:
+delib.module {
+  name = "user";
+
+  nixos.always = {myconfig, ...}: let
+    inherit (myconfig.constants) username;
+  in {
+    users = {
+      groups.${username} = {};
+
+      users.${username} = {
+        isNormalUser = true;
+        initialPassword = username;
+        extraGroups = ["wheel"];
+      };
+    };
+  };
+}
+```
+
+Если вы не использовали [модуль констант](#modules-constants), то содержание файла будет таким:
+```nix
+{delib, ...}:
+delib.module {
+  name = "user";
+
+  nixos.always.users = {
+    groups.sjohn = {}; #!!! REPLACEME
+
+    users.sjohn = { #!!! REPLACEME
+      isNormalUser = true;
+      initialPassword = "sjohn"; #!!! REPLACEME
+      extraGroups = ["wheel"];
+    };
+  };
+}
+```
+
+## Заключение
+Если вы чётко следовали инструкции, то в итоге у вас будет следующее дерево директории конфигурации:
+```plaintext
+hosts
+- desktop
+  - default.nix
+  - hardware.nix
+modules
+- config
+  - constants.nix
+  - home.nix
+  - hosts.nix
+  - rices.nix
+  - user.nix
+rices
+- dark
+  - default.nix
+flake.nix
+```
+
+Вы можете проверить, правильно ли всё сделали, с помощью команды:
+```sh
+nix flake check .#
+```