**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