sharix-open-config

Config policy — локальные конфигурации ShariX Open

Назначение каталогов

Конфигурация разделена на три слоя:

1. conf/ — отслеживаемые общие шаблоны и настоящая политика конфигурации.
2. conf-real/ — реальные файлы конкретного сервера, включая секреты.
3. Рабочие пути проекта и /etc/systemd/system/ — только символьные ссылки на соответствующие файлы в conf-real/.

Открытый репозиторий не должен содержать реальные пароли, API-ключи, локальные URL и выбранные на сервере режимы. conf-real/ исключён из основного Git, но сам является отдельным локальным Git-репозиторием без remote.

Управляемые файлы

Машиночитаемый перечень находится в conf/local-configs.tsv.

Рабочий путь	Реальный файл
.env	conf-real/.env
bin/install.cfg	conf-real/bin/install.cfg
handler environment	conf-real/handlers/.env (direct, no repository-local symlink)
handler runtime selection	conf-real/handlers/handler_runtime.json (direct, no repository-local symlink)
/etc/systemd/system/<имя>.service	conf-real/<имя>.service
/etc/systemd/system/handler@.service	conf-real/handler@.service

Шаблоны .env.example, bin/install.cfg.example, handlers/.env.example и handler_runtime.json.example остаются рядом с кодом, потому что там же поддерживается их схема. Шаблоны, для которых естественного *.example в коде нет, хранятся в conf/, например systemd-unit.

Каталоги conf/ejabberd/ и conf/ldap/ содержат шаблоны внешних сервисов. Они не мигрируются автоматически: их системные пути и владельцы зависят от ОС и конкретной схемы установки.

Системные пакеты ОС

Декларативные перечни обязательных пакетов поддерживаемых ОС находятся в conf/system-packages/. Они не являются частью conf-real и не устанавливаются прикладными install-скриптами: системные пакеты устанавливает и обновляет администратор сервера.

Для ALT Linux p11 используется system-packages/alt-p11.required.txt. В частности, для серверных HTTPS-запросов к ВТБ требуется системное хранилище доверия с Russian Trusted CA (ca-certificates-digital.gov.ru). После обновления CA выполните update-ca-trust, затем прикладную TLS-проверку модуля payments.

Установка и миграция старой установки

Команда:

./bin/configure_local_configs.sh --all

создаёт conf-real/, инициализирует в нём локальный Git, создаёт отсутствующие конфиги из примеров и формирует рабочие симлинки.

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

1. сохранить прежний файл в conf-real/;
2. при конфликте сделать резервную копию прежнего файла conf-real;
3. заменить рабочий путь симлинком.

При отказе файл остаётся как был. В неинтерактивном режиме legacy-файлы не переносятся без явного --yes.

Основной bin/install.sh, bin/install_service.sh и bin/install_handlers.sh используют эту же политику.

Локальный version control

Установщик выполняет git init conf-real, но не создаёт remote и не делает автоматические коммиты. После проверки конфигурации рекомендуется:

cd /opt/sharix-open-webapp-base/conf-real
git status
git add .env bin/install.cfg \
  opensharix.service handler@.service
git diff --cached --check
git commit -m "Save local server configuration"

Не публикуйте этот репозиторий. Если нужен backup, используйте закрытое хранилище с контролем доступа и шифрованием.

Языки установки

Stage 15 использует три общих ключа корневого .env: UI_LANGUAGES (разрешённые статические языки интерфейса), CONTENT_LANGUAGES (языки пользовательского контента) и CONTENT_PRIMARY_LANGUAGE (язык канонических существующих полей). Списки задаются через запятую; UI-список дополнительно пересекается с реально установленными gettext-каталогами. Отсутствующий optional-модуль sharix_translations не делает primary content недоступным.

После изменения tracked .env.example сначала просмотрите результат нормализации, затем примените и проверьте его:

./venv/bin/python conf/utils/normalize_env.py --only-root --diff
./venv/bin/python conf/utils/normalize_env.py --only-root --write
./venv/bin/python conf/utils/normalize_env.py --only-root --check

Изменение CONTENT_PRIMARY_LANGUAGE не переписывает существующие business rows автоматически: это semantic declaration установки, поэтому его нельзя менять как способ массового перевода данных.

Как менять конфигурацию

Изменять можно как рабочий путь, так и файл внутри conf-real: симлинк ведёт к одному и тому же содержимому. После изменения параметров, загружаемых при старте, перезапустите соответствующий сервис.

Прикладной код всегда открывает обычный рабочий путь из дерева установки и не должен знать о расположении conf-real. Для атомарной записи Python-модули используют общую библиотеку sharix_config_io.py; она сохраняет рабочий симлинк и заменяет только конечный файл. Обычная запись через open(..., "w") также следует по симлинку, но не обеспечивает атомарность при аварии процесса.

Как добавить новый локальный конфиг

1. Добавить безопасный пример *.example рядом с кодом либо в conf/.
2. Добавить строку в conf/local-configs.tsv.
3. Убедиться, что файл исключён из публичного Git.
4. Для записи из Python передавать рабочий путь в функции из sharix_config_io.py; не дублировать readlink, resolve и временные файлы по отдельным модулям.

5. Не добавлять реальные секреты в conf/, документацию или install-логи.

   Shared-module env parity (Stage 18.1)

Open и Platform остаются разными assemblies с независимыми корневыми .env.example. shared-env-contract.json фиксирует только настройки модулей/transport contracts, которые реально применимы к обеим assemblies: canonical owner, тип и безопасный default. Canonical checker живёт в sharix-open-config; Platform config содержит операционную byte-equivalent копию checker/contract, потому что Platform устанавливает собственный sharix-platform-config, а не Open config.

Локальная DB/network-independent проверка Open:

./venv/bin/python conf/utils/check_env_parity.py --assembly open --example .env.example

Cross-assembly проверка двух checkout:

python3 conf/utils/check_env_parity.py \
  --open /opt/sharix-open-webapp-base/.env.example \
  --platform /root/pre-sharix-platform-webapp-base/.env.example

Contract сознательно не требует полной симметрии. Open-only Platform integration и Service payment/Ferma policy, Platform-only sync/matching/payout/Speed settings, Testkit personas и handler-local runtime env остаются у своих владельцев.

Stage 18.5 добавляет в shared parity contract общий optional browser transport: SHARIX_BROWSER_CHROMIUM_EXECUTABLE, SHARIX_BROWSER_PROFILE_ROOT, SHARIX_BROWSER_HEADLESS, SHARIX_BROWSER_TIMEOUT_SECONDS, SHARIX_BROWSER_LOCALE, SHARIX_BROWSER_TIMEZONE. Пустой profile root означает <BASE_DIR>/var/browser_profiles; профиль выбирается интеграцией через безопасный profile_key. На ALT Linux p11 Chromium для этой capability является условной системной зависимостью и описан в system-packages/alt-p11.browser-runtime.required.txt; прикладной installer его не устанавливает и browser binary автоматически не скачивает. PROMETHEUS_URL/PROMETHEUS_TIMEOUT, VTB_API_TOKEN и VTB_API_CREATE_BINDING_URL остаются compatibility aliases, а не canonical parity keys.

После обновления .env.example используется только существующий lifecycle: normalize_env.py --diff, затем --write, затем --check. --diff редактирует secret-like значения как <redacted>; существующие installation-local значения при --write сохраняются.

S92.5 перенос владельца generic handler/XMPP config

Ключи EJ_*, объявленные в shared-env-contract.json за sharix-open-handlers-backend, физически принадлежат корневому .env. Старые установки могли хранить их также в conf-real/handlers/.env. Проверка и перенос выполняются без вывода значений:

./venv/bin/python conf/utils/migrate_env_ownership.py --root .
./venv/bin/python conf/utils/migrate_env_ownership.py --root . --apply

По умолчанию выполняется dry-run. --apply копирует legacy-only значение в корневой owner атомарно и не удаляет старую строку: это ограниченный период совместимости до cross-assembly acceptance. Если оба owner содержат разные значения, перенос останавливается с конфликтом и не меняет файлы. После успешного переноса применяется обычный normalize_env.py --diff/--write/--check, затем перезапускается handler runtime. bin/install_handlers.sh выполняет тот же safe relocation до выхода из --config-only.