iac/apps/django/CONFIGURATION.md

# Конфигурация проекта sarex-backend (Django)

Документ описывает способы конфигурирования backend-сервиса `sarex` (Django) и
основные переменные окружения. Фронтенд-приложение `sarex-frontend` (шелл на
Module Federation) конфигурируется отдельно на этапе сборки — см. раздел в конце
и `ENDPOINTS.md`.

## Способы конфигурирования

Сервис — это Django-приложение (проект `config`, бизнес-логика в пакете `sarex`).
Конфигурация складывается из двух механизмов:

1. **Модуль настроек Django** выбирается переменной `DJANGO_SETTINGS_MODULE`.
   Модули лежат в `config/settings/` и наследуются друг от друга через
   `from .base import *`.
2. **Переменные окружения** читаются двумя способами:
   - `django-environ` — объект `env = environ.Env()` в `config/settings/base.py`,
     вызовы `env('NAME', default=...)`, `env.bool(...)`, `env.list(...)`,
     `env.str(...)`;
   - `pydantic-settings` — классы-наследники `BaseSettings` с `env_prefix`
     (напр. `ServerSettings` → префикс `SERVER_`), инстанцируются как синглтоны
     (`SERVERSETTINGS = ServerSettings()` и т.п.).

Приложение **не загружает `.env` автоматически** в основном конфиге
(`DJANGO_READ_DOT_ENV_FILE` закомментирован). Исключение — pydantic-классы
`SentrySettings` (читает `.env.base`, `.env`), `ZitadelSettings`, `KafkaSettings`
(читают `.env`). В остальном переменные нужно экспортировать в окружение процесса.

### Модули настроек (`config/settings/*.py`)

| Модуль | Назначение |
| --- | --- |
| `base.py` | Базовые настройки, все классы `*Settings`, INSTALLED_APPS, DRF, Celery-очереди |
| `production.py` | Продакшн: `DEBUG=False`, БД из `DJANGO_POSTGRES_*`, SimpleJWT (RS512), логирование |
| `docker.py` | Наследует `test.py`, `ALLOWED_HOSTS=["*"]`, БД на хосте `postgres` |
| `test.py` / `test_ksg.py` | Прогон тестов |
| `example.local.py` / `example.ldap.local.py` | Шаблоны для локального `local.py` (копируются вручную) |

По умолчанию `manage.py` и `config/celery.py` используют `config.settings.local`.
В кластере задаётся `DJANGO_SETTINGS_MODULE=config.settings.production`, при этом
файл `production.py` **подменяется** ConfigMap-ом `django-configmap` (монтируется в
`/opt/sarex/config/settings/production.py`) — см. раздел про деплой.

### Способы запуска процессов

| Процесс | Команда | Назначение |
| --- | --- | --- |
| Web/API (uWSGI) | `uwsgi --plugin python3 --ini uwsgi.ini` | HTTP API на `0.0.0.0:8000`, модуль `config.wsgi:application` |
| Web/API (dev) | `python manage.py runserver` | Локальный запуск |
| Celery worker+beat | `celery -A config worker -B -l info -E -Q default -n default_worker.%h` | Фоновые задачи и периодические таски |
| Миграции | `python manage.py migrate` | Выполняются в `entrypoint.sh` перед стартом uWSGI |

Порядок запуска контейнера backend (`entrypoint.sh`): сначала
`opentelemetry-instrument python manage.py migrate`, затем
`opentelemetry-instrument uwsgi --plugin python3 --ini uwsgi.ini`. В кластере
перед `entrypoint.sh` секреты из Vault экспортируются в окружение (`set -a; . /vault/secrets/...`).

## Переменные приложения

Ниже перечислены основные переменные. Дефолт `—` означает, что значение
обязательно (в `production.py` без него будет ошибка старта).

### Django core

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `DJANGO_SETTINGS_MODULE` | string | `config.settings.local` | Модуль настроек Django |
| `DJANGO_DEBUG` | bool | `False` | Режим отладки |
| `DJANGO_ISOLATED` | bool | `False` | Изолированный режим (в configmap отключает Sentry) |
| `ALLOWED_HOSTS` | list/str | — (в prod из env) | Разрешённые хосты; в кластере `*` |
| `APPEND_SLASH` | bool | `True` | Автодобавление слеша в URL |
| `FZ152_COMPLIANCE` | bool | `False` | Режим соответствия 152-ФЗ |
| `PDM_SYNC` | bool | `False` | Синхронизация с PDM |
| `OBJECT_STORAGE_SYNC` | bool | `True` | Синхронизация с объектным хранилищем |
| `SECRET_KEY` | string | хардкод в `production.py` | Секретный ключ Django |
| `SIMPLE_JWT_ISSUER` | string | `django` | Issuer для JWT |
| `DISK_USAGE_ROOT` | string | `/` | Корень для расчёта занятого места |
| `USE_SSL_FOR_URL_SERIALIZATION` | bool | `True` | Использовать https при сериализации URL |
| `WEB_APP_AUTH_MODE` | string | `JWTDefault` | Режим авторизации веб-приложения |

### База данных (PostgreSQL)

Читаются в `config/settings/production.py`. В кластере приходят из Vault-секрета
`secrets/data/postgresql/apps/django` (файл `/vault/secrets/django-postgresql`).

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `DJANGO_POSTGRES_HOST` | string | — | Хост PostgreSQL |
| `DJANGO_POSTGRES_PORTS` | string | `5432` | Порт PostgreSQL |
| `DJANGO_POSTGRES_DATABASE` | string | — | Имя базы |
| `DJANGO_POSTGRES_USER` | string | — | Пользователь |
| `DJANGO_POSTGRES_PASSWORD` | string | — | Пароль |

Движок БД — `django_prometheus.db.backends.postgresql`.

### JWT (SimpleJWT, RS512)

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `JWT_PRIVATE_KEY` | string | — | Приватный RSA-ключ подписи (`\n` заменяются на переводы строк). В кластере — из Vault `rsa_keys` |
| `JWT_PUBLIC_KEY` | string | — | Публичный RSA-ключ проверки |
| `JWT_KID` | string | `None` | `kid` в заголовке токена (используется для межсервисных вызовов) |
| `DJANGO_JWT_SECRET` | string | `Froom too much love of living` | Легаси-секрет |

### Celery (`CELERY_*`)

Брокер — RabbitMQ; backend результатов — Redis (по умолчанию) или Postgres
(`CELERY_USE_POSTGRES=True`). `CELERY_RABBITMQ_*` в кластере из Vault-секрета
`secrets/data/rabbitmq/apps/django`.

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `CELERY_USE_POSTGRES` | bool | `False` | Использовать Postgres как result backend |
| `CELERY_RABBITMQ_HOST` | string | `localhost` | Хост RabbitMQ |
| `CELERY_RABBITMQ_PORT` | int | `5672` | Порт |
| `CELERY_RABBITMQ_USER` | string | `rabbit` | Пользователь |
| `CELERY_RABBITMQ_PASSWORD` | string | `rabbit` | Пароль |
| `CELERY_RABBITMQ_VHOST` | string | `api` | Виртуальный хост |
| `CELERY_REDIS_HOST` | string | `localhost` | Хост Redis (result backend) |
| `CELERY_REDIS_PORT` | int | `6379` | Порт Redis |
| `CELERY_REDIS_DATABASE` | int | `0` | Номер БД Redis |
| `CELERY_POSTGRES_DATABASE` | string | `celery_db` | БД для result backend на Postgres |
| `CELERY_POSTGRES_USER` | string | `sarex` | Пользователь |
| `CELERY_POSTGRES_PASSWORD` | string | `sarex` | Пароль |
| `CELERY_POSTGRES_HOST` | string | `localhost` | Хост |
| `CELERY_POSTGRES_PORT` | string | `5432` | Порт |

Дополнительно из Vault-шаблона прокидываются дублирующие `DJANGO_RABBIT_HOSTNAME`,
`DJANGO_RABBIT_USER`, `DJANGO_RABBIT_PASS`, `DJANGO_RABBIT_VHOST`, а также
`DJANGO_REDIS_HOST` / `DJANGO_REDIS_PORT`.

### Кеш Redis (`CACHE_*`)

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `CACHE_HOST` | string | `localhost` | Хост Redis |
| `CACHE_PORT` | int | `6379` | Порт |
| `CACHE_PASSWORD` | string \| null | `None` | Пароль |
| `CACHE_SSL` | bool | `False` | TLS |
| `CACHE_SSL_CA_CERTS` | string \| null | `None` | CA-сертификат |

### S3 / объектное хранилище (`S3_*`)

`S3_*` в кластере из Vault-секрета `secrets/data/minio/apps/django`.

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `S3_HOST` | string | `https://storage.yandexcloud.net` | Эндпоинт S3 |
| `S3_LOGIN` | string | `""` | Access key |
| `S3_PASSWORD` | string | `""` | Secret key |
| `S3_BUCKET` | string | `sarex-media-storage` | Бакет по умолчанию |
| `S3_REGION` | string | `""` | Регион (fallback: `AWS_DEFAULT_REGION`) |
| `AWS_S3_ENDPOINT_URL` | string | `https://storage.yandexcloud.net` | Эндпоинт (легаси-переменная) |
| `S3TOOLS_LIB_PATH` | string | `/opt/sarex/lib/s3tools.so` | Путь к нативной библиотеке загрузки (Dockerfile) |
| `S3TOOLS_WORKERS` | int | `10` | Число воркеров загрузки |

### Kafka (`KAFKA_*`)

Аутентификация в кластере из Vault-секрета `secrets/data/kafka/apps/django`.
Продюсер создаётся только при `SERVER_KAFKA_ENABLED=True`.

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `KAFKA_BOOTSTRAP_SERVERS` | list[str] (JSON) | `["localhost:9092"]` | Список брокеров |
| `KAFKA_SECURITY_PROTOCOL` | string | `""` | Протокол безопасности |
| `KAFKA_SASL_MECHANISM` | string | `""` | SASL-механизм |
| `KAFKA_SASL_PLAIN_USERNAME` | string | `user` | Логин |
| `KAFKA_SASL_PLAIN_PASSWORD` | string | `password` | Пароль |
| `KAFKA_SSL_CAFILE` | string | `""` | Путь к CA-сертификату |
| `KAFKA_TOPICS` | dict (JSON) | `{}` | Маппинг логических имён на топики |

### Sentry (`SENTRY_*`)

Читается классом `SentrySettings` из `.env.base` / `.env`.

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `SENTRY_USE` | bool | `True` | Включить Sentry |
| `SENTRY_HOST` | string | `""` | DSN/хост Sentry |
| `SENTRY_ENVIRONMENT` | string | `""` | Окружение |
| `SENTRY_TRACES_SAMPLE_RATE` | float | `1.0` | Доля трейсов |
| `SENTRY_PROFILES_SAMPLE_RATE` | float | `0.1` | Доля профилей |

### Флаги приложения (`SERVER_*`, класс `ServerSettings`)

Класс содержит десятки булевых флагов и параметров. Наиболее значимые (реально
задаются в манифестах):

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `SERVER_HOST` | string | `https://lk.sarex.io` | Внешний хост ЛК |
| `SERVER_API_HOST` | string | `https://api.sarex.io` | Внешний хост API |
| `SERVER_ZITADEL_ENABLED` | bool | `True` | Включить Zitadel-аутентификацию |
| `SERVER_KAFKA_ENABLED` | bool | `False` | Включить Kafka-продюсер |
| `SERVER_USE_METASHAPE` | bool | `True` | Использовать Metashape |
| `SERVER_USE_CLICKHOUSE` | bool | `False` | Использовать ClickHouse |
| `SERVER_CACHE_ENABLED` | bool | `False` | Включить кеш (в configmap выставляется `True`) |
| `SERVER_USE_NOTIFICATIONS` | bool | `True` | Уведомления |
| `SERVER_TIMEOUT` | int | `60` | Таймаут по умолчанию |
| `SERVER_CHUNKED_PATH` | string | — | Путь для чанкованных загрузок |

Полный список полей — в `ServerSettings` (`config/settings/base.py`). Любое поле
переопределяется переменной `SERVER_<FIELD>` в верхнем регистре.

### Workflows / processing (`WORKFLOWS_*`, класс `WorkFlowsSettings`)

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `WORKFLOWS_USE` | bool | `False` | Включить интеграцию с processing |
| `WORKFLOWS_HOST` | string | `https://api.sarex.io` | Хост сервиса processing |
| `WORKFLOWS_BASE_HOST` | string | `https://lk.sarex.io` | Базовый хост |
| `WORKFLOWS_PREFIX` | string | `/internal/v1` | Префикс внутреннего API |
| `WORKFLOWS_TIMEOUT` | int | `120` | Таймаут |
| `WORKFLOWS_REGISTRY` | string | `cr.yandex/crp3ccidau046kdj8g9q` | Реестр образов задач |
| `WORKFLOWS_TAG` | string | `stable` | Тег образов |

### Внешние API-сервисы (`BaseApiServiceMixin`)

Классы `GateWaySetttings` (`GATEWAY_`), `BimV2ApiSettings` (`BIMV2_`),
`EAVSettings` (`EAV_`), `AnalyticsSettings` (`ANALYTICS_`),
`DocumentationSettings` (`DOCUMENTATION_`), `UsersSettings` (`USERS_`),
`SystemLogSettings` (`SYSTEM_LOG_`), `ResourceSettings` (`RESOURCES_`) наследуют
общий набор полей:

| Поле (переменная `<PREFIX>_<FIELD>`) | Тип | Назначение |
| --- | --- | --- |
| `HOST` | string | Внешний хост сервиса |
| `API_PREFIX` | string | Префикс публичного API |
| `INTERNAL_HOST` | string | Внутренний хост (внутрикластерный) |
| `INTERNAL_PREFIX` | string | Префикс внутреннего API |
| `TIMEOUT` | int | Таймаут запроса |
| `ENABLE` | bool | Включён ли сервис |

Реально задаваемые в манифестах: `BIMV2_INTERNAL_HOST`, `BIMV2_TIMEOUT`,
`EAV_ENABLE`. Отдельно — `GK_ENCRYPTION_KEY` (класс `GatekeeperSettings`).

### Measurements (`MEASUREMENTS_*`)

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `MEASUREMENTS_HOST` | string | `https://api.sarex.io/measurements/` | Хост сервиса измерений |
| `MEASUREMENTS_TIMEOUT` | int | `180` | Таймаут |
| `MEASUREMENTS_WINDOW_SIZE` | int | `1000` | Размер окна |

### ClickHouse (`CLICKHOUSE_*`)

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `CLICKHOUSE_HOST` | string | `rc1d-...yandexcloud.net` | Хост |
| `CLICKHOUSE_PORT` | int | `9000` | Порт |
| `CLICKHOUSE_USER` / `CLICKHOUSE_PASSWORD` | string | `""` | Учётные данные |
| `CLICKHOUSE_DATABASE` | string | `values_db` | База |
| `CLICKHOUSE_TABLE` | string | `values` | Таблица |
| `CLICKHOUSE_SECURE` / `CLICKHOUSE_VERIFY` | bool | `False` | TLS и проверка сертификата |
| `CLICKHOUSE_CERT` | string | `""` | CA-сертификат |

### Zitadel (`ZITADEL_*`) и Keycloak (`KC_*`, `KC_SYNC*`)

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `ZITADEL_HOST` | string | `""` | Хост Zitadel (IdP) |
| `ZITADEL_ACCESS_TOKEN` | string | `""` | Сервисный токен (из Vault `django_auth`) |
| `ZITADEL_USERS_ENDPOINT` | string | `/v2/users` | Эндпоинт пользователей |
| `KC_SYNC_ENABLE` | bool | `False` | Включить синхронизацию с Keycloak |
| `KC_USE_REDIRECT_LOGOUT` | bool | `False` | Redirect при logout |
| `KC_CLIENT_ID` / `KC_CLIENT_SECRET` / `KC_DISCOVERY_URL` / `KC_REALM` | string | см. `KeyCloakSettings` | Параметры клиента Keycloak |

### Трейсинг (`TRACING_*`)

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `TRACING_SERVICE_NAME` | string | `backend.sarex-stage` | Имя сервиса в трейсах |
| `TRACING_ENDPOINT` | string | `localhost:4317` | OTLP-коллектор |
| `TRACING_INSECURE` | bool | `False` | Без TLS |
| `TRACING_ENVIRONMENT` | string | `prod` | Окружение |

### Comparator и прочее

| Переменная | Значение по умолчанию | Назначение |
| --- | --- | --- |
| `COMPARATOR_URL` | `https://wb.sarex.io/comparator` | URL сервиса сравнения |
| `COMPARATOR_SECTION` | `sarex-production-storage` | Секция хранилища |
| `COMPARATOR_JWT` | `default_jwt` | Токен сравнения |
| `WORKFLOWSSETTINGS_HOST` / `WORKFLOWSSETTINGS_REGISTRY` | — | Используются напрямую в configmap `production.py` |
| `PG_NODE_HOST`, `PG_API_KEY`, `PG_MONGO_HOST`, `PG_MONGO_PORT`, `PG_IMPORT_PATH` | см. `base.py` | Легаси-интеграции PG |

## Конфигурация в кластере (Kubernetes)

Манифесты приложения — в этом же каталоге (`base/`, оверлеи `brusnika-stage`,
`brusnika-prod`, `yc-k8s-test`). Секреты монтируются через **Vault Agent Injector**
(аннотации `vault.hashicorp.com/*` на Deployment `backend` и `celery`). Файлы
секретов в контейнере и их содержимое:

| Файл `/vault/secrets/...` | Секрет Vault | Переменные |
| --- | --- | --- |
| `django-postgresql` | `secrets/data/postgresql/apps/django` | `DJANGO_POSTGRES_HOST/PORTS/DATABASE/USER/PASSWORD` |
| `django-rabbitmq` | `secrets/data/rabbitmq/apps/django` | `CELERY_RABBITMQ_*`, `DJANGO_RABBIT_*` |
| `django-s3` | `secrets/data/minio/apps/django` | `AWS_S3_ENDPOINT_URL`, `S3_HOST/BUCKET/LOGIN/PASSWORD` |
| `django-kafka` | `secrets/data/kafka/apps/django` | `KAFKA_BOOTSTRAP_SERVERS/SECURITY_PROTOCOL/SASL_*` |
| `django-jwt-private` / `django-jwt-public` | `secrets/data/vault/common/rsa_keys` | `JWT_PRIVATE_KEY` / `JWT_PUBLIC_KEY` |
| `django-common` | `secrets/data/vault/common/django_auth` | `ZITADEL_ACCESS_TOKEN` |

Контейнер экспортирует эти файлы в окружение до запуска (`set -a; . /vault/secrets/...`).
Кроме того, `production.py` из ConfigMap содержит функцию `_load_env_file`, которая
подхватывает те же файлы при запуске `manage.py` через `kubectl exec` вне entrypoint.

Остальные (несекретные) переменные задаются в блоке `env` контейнеров
`backend`/`celery` (`SERVER_*`, `WORKFLOWS_*`, `BIMV2_*`, `MEASUREMENTS_*`,
`ZITADEL_HOST`, `KAFKA_TOPICS`, `EAV_ENABLE`, `PDM_SYNC`, `JWT_KID` и др.).

ConfigMap `django-configmap` подменяет `config/settings/production.py`
(смонтирован в `/opt/sarex/config/settings/production.py`) и переопределяет
`ALLOWED_HOSTS`, CORS, `DATABASES`, `SIMPLE_JWT`, `REST_FRAMEWORK`, `MIDDLEWARE`,
`KeyCloakSettings`, `SAREX_MODULES`, а также включает Sentry (если не `ISOLATED`).
ConfigMap `zitadel-configmap` содержит `config.json` с `client_id`/`host` Zitadel.
`uwsgi-configmap` монтирует `uwsgi.ini`.

## CI (`.gitlab-ci.yml`)

Пайплайн подключает общие шаблоны из `generic/common-ci`
(`common-security-scan.yaml`, `universal-pipeline.yaml`) и переключает окружение
по ветке/тегу через `workflow.rules`:

| Условие | STAND | NAMESPACE |
| --- | --- | --- |
| ветка `stage` | `stage` | `aero` |
| ветка `master` | `preprod` | (см. правила) |
| тег | `prod` | (см. правила) |

Ключевые переменные: `SERVICE_NAME=backend`, `DOCKERFILE_PATH=./Dockerfile`,
`RELEASE_NAME`, `CHART_NAME`, `CHART_VERSION`, `HELM_SET_ARGS`
(`universal-chart.services.backend.image.name…`, `…celery.image.name…`).

## Замечания и потенциальные проблемы

- В `production.py` `SECRET_KEY` задан хардкодом (закомментированный `env('SECRET_KEY')`).
  Для реального прод-развёртывания ключ желательно вынести в секрет.
- Основной конфиг не читает `.env` автоматически; переменные нужно экспортировать
  в окружение (в кластере это делает Vault + `set -a`). Только `SENTRY_*`,
  `ZITADEL_*`, `KAFKA_*` читаются из файлов `.env.base`/`.env` их pydantic-классами.
- `production.py` в репозитории backend и `production.py` из ConfigMap `django-configmap`
  — **разные** файлы. В кластере используется версия из ConfigMap (в ней, в частности,
  выставлено `DEBUG=True` в конце и включён `corsheaders`).
- `DATABASES['default']['ENGINE']` — `django_prometheus.db.backends.postgresql`
  (обёртка для метрик Prometheus).
- Значения `SERVER_*`-флагов у `backend` и `celery` местами различаются
  (напр. `SERVER_ZITADEL_ENABLED`, `SERVER_API_HOST`) — это ожидаемо.

## Минимальный набор для локального запуска

Согласно `README.md` backend: поднять Postgres/Redis/RabbitMQ (docker-compose),
скопировать шаблон настроек `cp config/settings/example.local.py config/settings/local.py`,
применить миграции (`python manage.py migrate`) и создать суперпользователя.
Минимально требуются переменные БД (`DJANGO_POSTGRES_*` или значения в `local.py`),
брокера Celery (`CELERY_RABBITMQ_*`) и, при использовании соответствующих функций,
`S3_*`, `JWT_PRIVATE_KEY`/`JWT_PUBLIC_KEY`. Примеры значений — в `.env.example`
рядом с этим файлом.