Docs of environments

docs/ru/environment.md

@@ -1,2 +1,120 @@
 # Настройки окружений
 
+Приложение может работать в разных окружениях: начиная с боевой площадки, заканчивая песочницей разработчика, иногда 
+имеющей некоторые отличия или ограничения. Разные окружения требуют разных настроек и наборов некоторых файлов. Console Jedi 
+читает из каталога `/environments` список окружений и с помощью консольных команд умеет их применять.
+
+## Хранилище окружений
+
+Каталог с настройками окружений `/environments` должен находится в корне проекта. Каталог состоит из:
+
+```
+/dev                // Каталог с файлами dev-окружения.
+    config.php      // Конфигурация dev-окружения.
+/prod               // Каталог с файлами prod-окружения.
+    config.php      // Конфигурация prod-окружения.
+index.php           // Список существующих окружений.
+```
+
+По-умолчанию в Console Jedi присутствует две заготовки под окружения: dev и prod. Вы можете удалить их, заменить или 
+добавить другие.
+
+Применение настроек окружения производится через консольную команду `env:init <type>`, вызов которой приводит к выполению 
+инструкций, описанных в файле `/environments/<type>/config.php` и копированию всех остальных файлов, найденных в 
+`/environments/<type>`.
+
+Скрипт `/environments/<type>/config.php` должен возвращать массив с инструкциями по настройке окружения. Все настройки 
+являются необязательными, и вовсе могут отсутствовать. Поддерживаемые настройки: 
+
+Настройка | Значение | Описание
+--- | --- | ---
+settings | array | Массив конфигурации для файла `.settings.php`.
+licenseKey | string | Лицензионный ключ продукта.
+modules | array | Список модулей, которые необходимо зарегистрировать в системе.
+options | array | Настройки модулей. Ключи элементов массива являются названиями модулей. Внутри элемента указывается код параметра и его значение.
+cluster | array | Настройки модуля «Веб-кластер».
+cluster[memcache] | array | Список мемкешей, которые должен использовать модуль «Веб-кластер».
+
+
+Пример:
+```php
+<?php
+
+return [
+    'settings' => [
+        'connections' => [
+            'default' => [
+                'host' => 'host',
+                'database' => 'db',
+                'login' => 'login',
+                'password' => 'pass',
+                'className' => '\\Bitrix\\Main\\DB\\MysqlConnection',
+                'options' => 2,
+            ]
+        ]
+    ],
+    'licenseKey' => 'NFR-123-456-789',
+    'modules' => [
+        'iblock',
+        'notamedia.i18n'
+    ],
+    'options' => [
+        'main' => [
+            'server_name' => 'star-wars.dev',
+            'email_from' => '[email protected]'
+        ]
+    ],
+    'cluster' => [
+        'memcache' => [
+           [
+               'GROUP_ID' => 1,
+               'HOST' => 'host',
+               'PORT' => 'port',
+               'WEIGHT' => 'weight',
+               'STATUS' => 'status',
+           ],
+           [
+               'GROUP_ID' => 1,
+               'HOST' => 'host',
+               'PORT' => 'port',
+               'WEIGHT' => 'weight',
+               'STATUS' => 'status',
+           ]
+        ]
+    ]
+];
+```
+
+Попробуем на практике. Создадим окружение с кодом `r2`.
+
+1. Создайте каталог `/environments/r2`.
+1. Предположим, что в проекте в окружении r2 нужен файл `/directory/file.txt`. Поэтому, поместим его в настройки 
+окружения: `/environments/r2/directory/file.txt`.
+1. Создайте файл с инструкциями по настройке окружения: `/environments/r2/config.php`. Данный скрипт должен 
+возвращать массив (можно и пустой).
+1. Окружение готово, осталось всего лишь зарегистрировать его. В файле `/environments/index.php` добавим новый элемент 
+массива:
+
+```
+'r2' => [
+    'name' => 'R2-D2', // Полное название окружения, отображается в интерфейсе Console Jedi.
+    'path' => 'r2' // Каталог с окружением, относительно текущего файла.
+],
+```
+
+Запустите команду `env:init r2`. Будет скопирован файл из `/environments/r2/directory/file.txt` в `/directory/file.txt` и 
+выполнены указания, описанные в файле `config.php`.
+
+## Рекомендации
+
+Настройки в «Битриксе» задаются двумя способами: через [`.settings*.php`](https://dev.1c-bitrix.ru/learning/course/?COURSE_ID=43&LESSON_ID=2795) 
+и с помощью настроек модулей. Первым способом предпочтительнее задавать неизменяемые параметры, при чём рекомендуется 
+работать с файлом `.settings_extra.php`, тем самым переназначив настройки, указанные в `.settings.php`. Разместите в 
+каталоге с окружением файл `/<real>/<path>/.settings_extra.php`, возвращающий массив, и опишите в нём необходимые 
+данному окружению настройки.
+
+Не смотря на то, что Console Jedi позволяет управлять настройками модулей и их регистрацией, использовать эту возможность 
+нужно крайне осторожно, потому что установка и удаление модулей, изменение их параметров — это операции изменения БД, 
+которые должны производиться только через миграции. К примеру, вы просто не сможете удалить модуль из системы, используя 
+настройки окружений. Установка модулей через настройки окружений не годна для продакшена, но хороша для дева и теста: 
+например, так можно установить модуль для дебага или автотестов.

tmpl/environments/dev/config.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Example settings file config.php:
+ * Example of settings file config.php:
  *
  * ```php
  * return [

tmpl/environments/index.php

@@ -7,10 +7,10 @@
  *
  * ```php
  * return [
- *      '<key>' => [
- *          'name' => '<Environment name>',
- *          'path' => '<dir-path>'
- *      ]
+ *  '<type>' => [
+ *      'name' => '<Full name>',
+ *      'path' => '<directory>'
+ *  ]
  * ];
  * ```
  */

tmpl/environments/prod/config.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Example settings file config.php:
+ * Example of settings file config.php:
  * 
  * ```php
  * return [