Initial commit: VMware vSphere API simulator scaffold.

Add the FastAPI app, PostgreSQL migrations, Docker/Helm packaging, API
contracts, docs, client examples, and the unit/integration/compatibility
test suite for local client and tooling labs without a real vCenter.

docs/ru/getting-started.md

@@ -0,0 +1,176 @@
+**Language / Язык:** [English](../getting-started.md) | [Русский](getting-started.md)
+
+# Быстрый старт
+
+Поднимите локальную лабораторию vSphere, пройдите аутентификацию и выполните первый
+цикл чтения/мутации против симулятора.
+
+## Требования
+
+- Docker и Docker Compose
+- `make` (необязательно, но используется в документированных командах)
+
+Python, линтеры и тесты запускаются **внутри** контейнеров. Для повседневной работы
+локальный Python-инструментарий не нужен.
+
+## Выберите путь
+
+| Путь | Когда использовать |
+|---|---|
+| [Опубликованный образ](#1a-опубликованный-образ-docker-hub) | Самая быстрая лаборатория на `inecs/vmware-api-simulator` |
+| [Helm / Kubernetes](kubernetes.md) | Установка в кластер с Ingress + Let's Encrypt |
+| [Development checkout](#1b-development-checkout) | Вклад в код / bind-mount исходников |
+
+## 1a. Опубликованный образ (Docker Hub)
+
+Использует [`docker-compose.release.yml`](../../docker-compose.release.yml) — PostgreSQL +
+runtime-симулятор + HTTPS gateway с Hub. Сборка исходников не нужна, но Compose
+нужно запускать из **checkout этого репозитория**, чтобы смонтировались
+`docker/gateway/` и `docker/tls/`. Seed выполняется автоматически после готовности
+симулятора.
+
+```bash
+# из git checkout этого репозитория (нужны docker/gateway и docker/tls)
+docker compose -f docker-compose.release.yml pull
+docker compose -f docker-compose.release.yml up -d --wait
+```
+
+Закрепить версию:
+
+```bash
+IMAGE_TAG=0.1.0 docker compose -f docker-compose.release.yml up -d --wait
+```
+
+Make-хелперы (git checkout):
+
+```bash
+make release-up
+# опциональный повторный seed: make release-seed PROFILE=small
+```
+
+| Порт хоста | Сервис |
+|---|---|
+| `443` | HTTPS gateway (основная точка входа vCenter) |
+| `80` | HTTP lab face |
+| `5434` | PostgreSQL (только localhost) |
+
+Миграции выполняются автоматически через one-shot сервис `migrate`.
+
+Далее — с [Дождитесь готовности](#2-дождитесь-готовности).
+
+## 1b. Development checkout
+
+```bash
+make install
+make up
+```
+
+Сервисы (полная картина — [Порты](ports.md)):
+
+| Порт хоста | Сервис |
+|---|---|
+| `443` | HTTPS gateway (nginx) → simulator |
+| `80` | HTTP lab face |
+| `5434` | PostgreSQL (только localhost) |
+
+Миграции применяются автоматически до готовности симулятора. Внутренний
+процесс FastAPI слушает `8080` и на хост не публикуется.
+
+## 2. Дождитесь готовности
+
+```bash
+curl -sk https://localhost/health/live
+curl -sk https://localhost/health/ready
+```
+
+`/health/ready` возвращает HTTP 503, пока PostgreSQL недоступен **и** пока
+не применена последняя упакованная миграция.
+
+## 3. Засейте профиль
+
+```bash
+make seed                          # default: large — 10 hosts / 1000 VMs
+VSPHERE_PROFILE=small make seed
+```
+
+`small` создаёт 3-хостовый кластер с пятью именованными VM (`web-01`, `web-02`,
+`db-01`, `app-01`, `jumpbox`), datastores, standard portgroup и четырьмя
+лабораторными принципалами. Другие размеры — [Профили seed](seed-profiles.md).
+
+## 4. Проверьте версию API
+
+```bash
+curl -sk https://localhost/api/appliance/system/version | jq .
+```
+
+Catalog major при холодном старте по умолчанию — **9** (vSphere 8.0 U2 /
+поверхность Automation 9.1) в Docker Compose. Просмотр и hot-swap majors 6–9 —
+из Web UI или [Версии API](api-versions.md).
+
+## 5. Аутентификация
+
+```bash
+SID=$(curl -sk -u 'administrator@vsphere.local:VMware1!' \
+  -X POST https://localhost/api/session | tr -d '"')
+echo "$SID"
+```
+
+`SID` — это `vmware-api-session-id`. Передавайте его в каждом последующем
+вызове как заголовок (или опирайтесь на cookie, которую также выставляет
+ответ login):
+
+```bash
+curl -sk -H "vmware-api-session-id: $SID" https://localhost/api/vcenter/vm
+```
+
+Подробности: [Аутентификация](authentication.md).
+
+## 6. Список VM и включение одной
+
+```bash
+curl -sk -H "vmware-api-session-id: $SID" \
+  https://localhost/api/vcenter/vm | jq .
+
+curl -sk -X POST -H "vmware-api-session-id: $SID" \
+  "https://localhost/api/vcenter/vm/vm-104/power?action=start" | jq .
+```
+
+Power-действия и другие длительные операции возвращают CIS task id.
+Опрашивайте задачу до завершения:
+
+```bash
+curl -sk -H "vmware-api-session-id: $SID" \
+  "https://localhost/api/cis/tasks/${TASK_ID}" | jq .
+```
+
+## 7. Откройте Web UI
+
+Откройте [https://localhost/](https://localhost/) — интерактивная
+консоль, каталог эндпоинтов (vSphere majors 6–9), вид совместимости, apply
+runtime-контракта и управление demo-cluster. Скриншоты светлой/тёмной темы и
+полный список возможностей — [Web UI](web-ui.md).
+
+## 8. Попробуйте клиентскую библиотеку
+
+```bash
+# from the repository root after make up + seed
+python examples/python/vsphere_rest_smoke.py https://localhost
+python examples/python/vsphere_soap_smoke.py https://localhost
+```
+
+Другие стеки: [Клиенты](clients.md) и [`examples/`](../../examples/README.ru.md).
+
+## Готово, когда…
+
+- `/health/ready` возвращает `{"status": "ok"}` (или эквивалентное OK-тело)
+- `/api/appliance/system/version` сообщает версию активного catalog major
+- Session login успешен для `administrator@vsphere.local`
+- `/api/vcenter/vm` перечисляет seeded VM
+- Power-действие возвращает task id, который доходит до `SUCCEEDED`
+
+## Дальше
+
+- [Конфигурация](configuration.md) — env vars, workers, размер seed
+- [Версии API](api-versions.md) — hot-swap catalog majors 6–9
+- [Клиенты](clients.md) — Python, Ansible, Terraform, Pulumi
+- [Эксплуатация](operations.md) — reseed, migrate, upgrades