# Конфигурация проекта Attachments
# Версия: 0.11.1

Документ описывает все переменные окружения и способы конфигурирования сервиса.

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

Настройка сервиса выполняется **только через переменные окружения**. Отдельного файла с настройками (yaml/toml) в приложении нет — за конфигурацию отвечает `internal/config/settings.py` на базе `pydantic.BaseSettings`.

Источники переменных окружения по способам запуска:

| Способ запуска | Откуда берутся переменные |
| --- | --- |
| Локально (docker-compose) | Файл `.env` в корне (`env_file: .env` в `docker-compose.yml`), плюс `POSTGRES_PASSWORD` для контейнера БД |
| Kubernetes (Helm) | `.helm/values.yaml`: блок `envs` (обычные значения) и `secretEnvs` (значения из k8s-секретов) |
| CI/CD (GitLab) | `.gitlab-ci.yml`: переменные пайплайна и build-args |

Дополнительно секреты доступа к S3 не задаются напрямую, а читаются из JSON-файла (см. `YANDEX_S3_ACCOUNT_PATH` ниже).

## Переменные приложения (класс `Settings`)

Читаются напрямую по имени (регистрозависимо, `case_sensitive = True`). Переменные без значения по умолчанию **обязательны** — без них приложение не стартует.

| Переменная | Тип | Обязательна | Значение по умолчанию | Назначение |
| --- | --- | --- | --- | --- |
| `API` | str | нет | `/api` | Префикс всех HTTP-роутов |
| `NAME` | str | нет | `Attachments` | Имя сервиса (title в FastAPI/OpenAPI) |
| `VERSION` | str | нет | `0.0.1` | Версия сервиса |
| `DESCRIPTION` | str | нет | `Attachments` | Описание сервиса |
| `YANDEX_S3_ENDPOINT_URL` | str | да* | — | Endpoint S3 (без схемы; `https://`/`http://` добавляется в коде по `YANDEX_S3_USE_SSL`) |
| `YANDEX_S3_ACCESS_KEY_ID` | str | да* | — | Access Key ID для S3 |
| `YANDEX_S3_SECRET_ACCESS_KEY` | str | да* | — | Secret Access Key для S3 |
| `YANDEX_S3_USE_SSL` | bool | нет | `True` | Использовать ли HTTPS при обращении к S3 |
| `YANDEX_S3_REGION` | str | нет | `ru-central1` | Регион S3 |
| `YANDEX_S3_VERIFY` | bool | да | — | Проверять ли SSL-сертификат S3 |
| `BUCKET_NAME` | str | да | — | Имя бакета для вложений |
| `DATABASE_NAME` | str | да | — | Имя базы данных PostgreSQL |
| `DATABASE_USER` | str | да | — | Пользователь БД |
| `DATABASE_PASSWORD` | str | да | — | Пароль пользователя БД |
| `DATABASE_HOST` | str | да | — | Хост БД |
| `DATABASE_PORT` | int | да | — | Порт БД |
| `DATABASE_SSL_MODE` | str | да | — | Режим SSL при подключении к БД (напр. `disable`, `require`, `verify-full`) |

\* Три переменные `YANDEX_S3_ENDPOINT_URL`, `YANDEX_S3_ACCESS_KEY_ID`, `YANDEX_S3_SECRET_ACCESS_KEY` формально обязательны, но при старте приложения они **проставляются автоматически** функцией `json_config_s3_account_settings()` из JSON-файла (см. `YANDEX_S3_ACCOUNT_PATH`). Задавать их вручную не нужно, если задан путь к файлу.

## Настройки S3 через JSON-файл

| Переменная | Обязательна | Назначение |
| --- | --- | --- |
| `YANDEX_S3_ACCOUNT_PATH` | да | Путь к JSON-файлу с реквизитами сервисного аккаунта S3 |

При старте функция `json_config_s3_account_settings()` читает файл по этому пути и выставляет переменные окружения `YANDEX_S3_ENDPOINT_URL`, `YANDEX_S3_ACCESS_KEY_ID`, `YANDEX_S3_SECRET_ACCESS_KEY`.

Ожидаемая структура JSON-файла:

```json
{
  "endpoint": "storage.yandexcloud.net",
  "access_key_id": "<ключ>",
  "secret_access_key": "<секрет>"
}
```

В Kubernetes файл монтируется из секрета `attachments-s3-secret` (в prod — `yc-s3`) в `/etc/sarex/yc-s3-storage/yc-s3-service-account.json`.

## Логирование (класс `LoggerSettings`, префикс `LOG_`)

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `LOG_LEVEL` | str | `INFO` | Уровень логирования (`DEBUG`, `INFO`, `WARNING`, ...). При неизвестном значении откатывается на `INFO` |
| `LOG_FORMAT` | str | JSON-шаблон с полями `timestamp`, `level`, `message` | Формат строк лога (используется `pythonjsonlogger`) |

## Трейсинг / OpenTelemetry (класс `TraceSettings`, префикс `TRACING_`)

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `TRACING_USE` | bool | `False` | Включает OTEL-трейсинг, логгер и middleware |
| `TRACING_HOST` | str | `localhost:4317` | Адрес OTLP-коллектора |
| `TRACING_SERVICE_NAME` | str | `attachments` | Имя сервиса в трейсах |
| `TRACING_INSECURE` | bool | `False` | Небезопасное (без TLS) подключение к коллектору |

Трейсинг активируется только при `TRACING_USE=true`.

## Переменные инфраструктуры и сборки

Не читаются кодом приложения, но нужны для запуска/сборки/деплоя.

| Переменная | Где используется | Назначение |
| --- | --- | --- |
| `POSTGRES_PASSWORD` | `docker-compose.yml` (контейнер `db`) | Пароль суперпользователя PostgreSQL при локальном запуске |
| `PIP_EXTRA_INDEX_URL` | `docker/Dockerfile` (build-arg) | Доп. индекс pip для установки приватных пакетов при сборке образа |
| `GITLAB_PYPI_EXTRA_INDEX_URL` | `.gitlab-ci.yml` | Значение, пробрасываемое в `PIP_EXTRA_INDEX_URL` при сборке в CI |

### Переменные CI/CD (`.gitlab-ci.yml`)

Служебные переменные пайплайна: `SERVICE_NAME`, `DOCKERFILE_PATH`, `BUILD_ARGS`, `CI_TRIGGER_SOURCE`, а также подставляемые по окружениям `STAND`, `NAMESPACE`, `RELEASE_NAME`, `CHART_NAME`, `CHART_VERSION`, `K8S_HUSTLER_BRANCH`, `HELM_SET_ARGS`. Окружение выбирается по ветке/тегу: `stage` → ветка `stage`, `preprod` → ветка `master`, `production` → git-тег.

## Переменные из Helm-чарта (`.helm/values.yaml`)

Обычные переменные (`envs`):

| Переменная | Значение | Примечание |
| --- | --- | --- |
| `API_ADDRESS` | `0.0.0.0:8000` | Задаётся в чарте, но **кодом приложения не читается** |
| `POSTGRES_POOL_SIZE` | `10` | Задаётся в чарте, но **кодом приложения не читается** |
| `DATABASE_SSL_MODE` | `verify-full` | |
| `YANDEX_S3_VERIFY` | `true` | |
| `YANDEX_S3_ACCOUNT_PATH` | `/etc/sarex/yc-s3-storage/yc-s3-service-account.json` | |
| `BUCKET_NAME` | `attachments-stage-2` / `attachments-prod-2` | Зависит от окружения |

Переменные из секретов (`secretEnvs`, секрет `attachments-postgresql-secret` / `ya-pg-secret`):

| Переменная | Ключ секрета | Примечание |
| --- | --- | --- |
| `DATABASE_PORT` | `port` | |
| `DATABASE_HOST` | `host` | |
| `DATABASE_USER` | `username` | |
| `DATABASE_PASSWORD` | `password` | |
| `DATABASE_NAME` | `database` | |
| `YC-PG-CERTIFICATE` | `ca.crt` | CA-сертификат PostgreSQL; также монтируется файлом в `/root/.postgresql/root.crt` |

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

Для запуска через `docker-compose` в файле `.env` достаточно задать (см. `.env.example`):

- `POSTGRES_PASSWORD` — для контейнера БД
- `DATABASE_*` — параметры подключения к БД
- `BUCKET_NAME`, `YANDEX_S3_VERIFY`
- `YANDEX_S3_ACCOUNT_PATH` **или** напрямую `YANDEX_S3_ENDPOINT_URL` + `YANDEX_S3_ACCESS_KEY_ID` + `YANDEX_S3_SECRET_ACCESS_KEY`