**Language / Язык:** [English](../configuration.md) | [Русский](configuration.md)

# Конфигурация

Настройки приложения загружаются из окружения (см. `.env.example`).
Docker Compose инжектирует многие из них для сервиса `simulator`; значения,
объявленные в `environment:` в `docker-compose.yml`, переопределяют `.env` для этого
сервиса. Типизированная модель настроек находится в [`app/config.py`](../../app/config.py).

## Основное

| Переменная | По умолчанию / пример | Значение |
|---|---|---|
| `APP_HOST` | `0.0.0.0` | Адрес bind |
| `APP_PORT` | `8080` | Внутренний порт uvicorn (не публикуется; gateway публикует vCenter HTTPS) |
| `DATABASE_URL` | `postgresql://vmware:vmware@postgres:5432/vmware_simulator` | asyncpg DSN |
| `DB_POOL_MIN_SIZE` | `1` | Минимум пула |
| `DB_POOL_MAX_SIZE` | `10` | Максимум пула |
| `DB_CONNECT_TIMEOUT_SECONDS` | `10` | Таймаут подключения |
| `DB_COMMAND_TIMEOUT_SECONDS` | `30` | Таймаут команды |
| `LOG_LEVEL` | `INFO` | Уровень логирования |
| `REQUEST_ID_HEADER` | `X-Request-ID` | Заголовок корреляции запросов |

## vSphere seed inventory

| Переменная | По умолчанию | Значение |
|---|---|---|
| `SEED_VSPHERE_PROFILE` | `large` | `small` \| `large` \| `big` (`demo-cluster` = `big`) — см. [Профили seed](seed-profiles.md) |
| `SEED_VSPHERE_LARGE_HOSTS` | `10` | Число хостов для профиля `large` |
| `SEED_VSPHERE_LARGE_VMS` | `1000` | Число VM для профиля `large` |

## Опциональная legacy-плоскость

| Переменная | По умолчанию | Значение |
|---|---|---|
| `ENABLE_PVE_STUB` | `false` | Включает legacy Proxmox VE `/api2/*` stub-плоскость, унаследованную из общей platform lineage. Нативная vSphere `/api` + `/rest` + `/sdk` — основная плоскость по умолчанию независимо от этого флага. |

## Contract и catalog

| Переменная | Значение |
|---|---|
| `CONTRACT_SNAPSHOT` | Опциональный путь к нормализованному PVE-style snapshot (актуально только при `ENABLE_PVE_STUB=true`) |
| `CONTRACT_FALLBACK` | `error` (default), `schema-default`, или `fixture` — fallback-поведение для опциональной stub-плоскости |
| `COMPATIBILITY_EVIDENCE` | Опциональный путь к evidence JSON для отчётов совместимости |
| `CATALOG_ARTIFACT_URL_6` … `_9` | Метки catalog majors vSphere (6→7.0, 7→7.0 U3, 8→8.0, 9→8.0 U2); stub URLs, не live downloads |

Runtime hot-swap (Web UI / `POST /ui/api/contract/apply?major=N`) переключает
активный **catalog** major, используемый Web UI и compatibility/evidence
отчётами. Он не ограничивает зарегистрированную REST/SOAP поверхность — каждый
известный маршрут всегда обслуживается реальным обработчиком или DB-backed stub.
См. [Версии API](api-versions.md).

## Безопасность и задачи

| Переменная | Значение |
|---|---|
| `TICKET_SIGNING_KEY` | HMAC signing key для сессий (**меняйте вне toy labs**) |
| `TASK_WORKER_CONCURRENCY` | Число leased asyncio workers (1–32) |
| `TASK_LEASE_SECONDS` | Длительность lease PostgreSQL-задачи |
| `SIMULATION_TIME_SCALE` | Ускоряет симулированные длительности задач (выше = быстрее) |

## Client test hooks

| Переменная | Значение |
|---|---|
| `TEST_DATABASE_URL` | DSN для integration-тестов |
| `VSPHERE_BASE` | Базовый URL для cookbooks/probes (`https://localhost` с хоста, `http://simulator:8080` изнутри Compose) |

## Порты и TLS

| Endpoint | Назначение |
|---|---|
| `https://localhost` | Основная vCenter HTTPS точка входа (curl, browsers, pyvmomi, govmomi, Terraform, большинство examples) |
| `http://localhost` | HTTP-грань для лабораторных нужд |
| `localhost:5434` | PostgreSQL (только localhost) |
| Internal `simulator:8080` | Прямой процесс FastAPI; доступен только внутри Compose network |

Вшитый сертификат в `docker/tls/` — одноразовый development material.
Никогда не используйте его вне локальных labs. См. [Безопасность](security.md) и
[Порты](ports.md).

## Заметки по Compose

- `migrate` выполняется один раз; `simulator` ждёт успешного migrate.
- Development Compose bind-mount'ит репозиторий и включает Uvicorn reload.
- Сервис `api-gateway` (nginx) публикует `443`/`80` и проксирует на
  внутренний процесс `simulator:8080`; устанавливает `X-VMware-Service` /
  `X-Forwarded-Port`, чтобы будущие routers могли определить использованный listener.

## Открытые и неиспользуемые example keys

`.env.example` всё ещё перечисляет несколько ключей из общей platform lineage, которые
**не** потребляются текущей vSphere-first моделью настроек, в частности
`SIMULATION_SEED`, `SIMULATOR_ADMIN_ENABLED` и `SIMULATOR_ADMIN_TOKEN`. Не
предполагайте, что аутентифицированный admin API `/_simulator` существует сегодня — см.
[Безопасность](security.md).