Перейти к основному содержимому
Версия: 2.0 (WIP)

.env

Настройки приложения Памир могут храниться в двух источниках:

  • в базе данных PostgreSQL;
  • в dotenv-файлах, расположенных в директории приложения
    (по умолчанию: $HOME/.pamir).

При первом запуске приложения значения конфигурации считываются из dotenv-файлов. В дальнейшем часть параметров может быть изменена через интерфейс приложения и сохранена в базе данных. В этом случае значения, сохранённые в базе данных, имеют приоритет над значениями из dotenv-файлов.

Общий принцип​

Иерархия dotenv-файлов организована таким образом, чтобы:

  • при обновлении приложения автоматически получать новые параметры, появившиеся в новых версиях Памир;
  • не перезаписывать пользовательские настройки.

Переменные окружения делятся на следующие уровни:

  • служебные для сервиса;
  • верхнеуровневые общие;
  • верхнеуровневые для сервиса;
  • переопределяемые общие;
  • переопределяемые для сервиса.

При запуске контейнера переменные применяются последовательно: каждый следующий уровень может переопределять значения, заданные на предыдущем.

Приоритет источников конфигурации​

Итоговое значение параметра определяется по следующему приоритету:

  1. значение, сохранённое в базе данных;
  2. значение из .$SERVICE.override.env;
  3. значение из .override.env;
  4. значение из .$SERVICE.env;
  5. значение из .env;
  6. значение из .$SERVICE.autogen.

Структура dotenv-файлов​

ПриоритетФайлОбласть действияНазначение
1.$SERVICE.autogenсервис или группа сервисовСлужебный файл, автоматически генерируемый на этапе сборки. Содержит маршруты работающего сервиса и информацию о версии приложения.
2.envвсе сервисыОбщий верхнеуровневый файл. Содержит общие параметры приложения: подключения к базе данных, менеджеру очередей, key-value хранилищу, инфраструктурные и системные настройки.
3.$SERVICE.envсервис или группа сервисовВерхнеуровневый файл для конкретного сервиса или группы сервисов. Используется для задания параметров отдельных компонентов, например Monitoring или SRM.
4.override.envвсе сервисыОбщий переопределяемый файл. Используется для пользовательского переопределения параметров из .env без изменения базовой конфигурации поставки.
5.$SERVICE.override.envсервис или группа сервисовПереопределяемый файл для конкретного сервиса или группы сервисов. Используется для пользовательского переопределения параметров из .$SERVICE.env.
примечание

В таблице перечислены типы dotenv-файлов в логическом порядке структуры конфигурации. При вычислении итогового значения параметра более высокий приоритет имеют файлы переопределения: сначала .$SERVICE.override.env, затем .override.env, далее .$SERVICE.env, .env и .$SERVICE.autogen.

Описание файлов​

.$SERVICE.autogen​

Где $SERVICE — имя отдельного сервиса или группы сервисов.

Служебный dotenv-файл, автоматически формируемый на этапе сборки приложения. Содержит:

  • маршруты работающего сервиса;
  • сведения о версии приложения.

Файл имеет расширение .autogen и не предназначен для ручного редактирования.

.env​

Общий верхнеуровневый dotenv-файл.

Содержит базовые параметры, общие для всех сервисов приложения, в том числе:

  • параметры подключения к базе данных;
  • параметры подключения к менеджеру очередей;
  • параметры подключения к key-value хранилищу;
  • инфраструктурные настройки;
  • параметры внутренних служб удостоверяющего центра;
  • параметры каталогов пользователей;
  • параметры инициализации службы менеджера очередей.

При необходимости переопределения общих параметров исходные значения обычно берутся из этого файла.

.$SERVICE.env​

Где $SERVICE — имя отдельного сервиса или группы сервисов.

Верхнеуровневый dotenv-файл для конкретного сервиса или группы сервисов. Используется для задания параметров отдельных компонентов, например:

  • Monitoring;
  • SRM;
  • других сервисов платформы.

Для некоторых сервисов такой файл может отсутствовать. В этом случае сервис использует значения по умолчанию либо параметры, полученные из других уровней конфигурации.

.override.env​

Общий переопределяемый dotenv-файл.

Используется для переопределения параметров из общего файла .env. Все переменные, заданные в этом файле, становятся доступны всем сервисам приложения.

Файл отсутствует при первичной установке, но может быть создан пользователем. Его использование позволяет сохранять пользовательские настройки при обновлении приложения.

.$SERVICE.override.env​

Где $SERVICE — имя отдельного сервиса или группы сервисов.

Переопределяемый dotenv-файл для конкретного сервиса или группы сервисов. Используется для переопределения параметров из .$SERVICE.env.

Поведение аналогично .override.env, но область действия ограничена конкретным сервисом или группой сервисов.

Файл также отсутствует при первичной установке и может быть создан вручную. При обновлении приложения он не перезаписывается, что позволяет сохранять пользовательские настройки.

Рекомендации по использованию​

  • Не редактируйте файлы *.autogen вручную.
  • Для изменения общих параметров используйте .override.env.
  • Для изменения параметров отдельного сервиса используйте .$SERVICE.override.env.
  • Не вносите пользовательские изменения напрямую в .env и .$SERVICE.env, если требуется сохранить их при обновлении приложения.
  • Если параметр также поддерживает хранение в базе данных, значение из базы данных будет иметь приоритет над dotenv-файлами.

Применение изменений​

После внесения изменений в dotenv-файлы необходимо применить их с помощью утилиты pamirctl.

Применить настройки для всех сервисов​

pamirctl start

Применить настройки для отдельного сервиса​

pamirctl start $SERVICE

где $SERVICE — имя сервиса в docker-compose-файле или несколько сервисов, перечисленных через пробел.

Связанные разделы​