gpu-rent/docs/setup.md

# Подготовка до первого `up`

Цель: зелёный `doctor` → первый `up --yes` → UI на `http://127.0.0.1:17801` → `stop`.

Панель Selectel: [my.selectel.ru](https://my.selectel.ru).

**Важно:** ключ панели **`X-Token` не подходит**. Нужен сервисный пользователь + пароль (OpenStack Keystone). CLI сам получает токен на ~24 ч; в `.env` токен хранить не надо.

---

## Карта шагов

| # | Что сделать | Готово, когда |
| --- | --- | --- |
| 1 | Python 3.11+ и лаунчер | `.\gpu-rent.ps1 --help` печатает help |
| 2 | Проект + квота GPU > 0 | в панели лимит GPU ≥ 1 |
| 3 | Сервисный пользователь + `.env` | заполнены `OS_*` и `GPU_RENT_AZ` |
| 4 | (Опц.) Civitai + `models.yaml` | токен в `.env`, манифест с `modelVersionId` |
| 5 | (Опц.) `extensions.yaml` / Git | публичные репы без токена |
| 6 | `doctor` | exit 0 |
| 7 | Первый `up --yes` | браузер / :17801 |
| 8 | `stop` | compute удалён, диски на месте |

SSH-ключ руками не нужен — CLI создаст `.gpu-rent/id_ed25519` при первом `up`.

---

## 1. Python и лаунчер

Нужен **Python 3.11+**. На Windows при установке включи «Add python.exe to PATH».

В корне репозитория:

```powershell
.\gpu-rent.ps1 --help
```

```bat
gpu-rent.bat --help
```

```bash
chmod +x gpu-rent.sh
./gpu-rent.sh --help
```

Лаунчер сам создаёт `.venv` и ставит пакет. Первый запуск копирует шаблоны **в корень репо**, если файлов нет:

- `env.example` → `.env`
- `models.example.yaml` → `models.yaml`
- `extensions.example.yaml` → `extensions.yaml`
- `ollama-models.example.yaml` / `llamacpp-models.example.yaml` → соответствующие yaml (лаунчер / setup)
- `gpu-rent.vars.example` → `gpu-rent.vars`

Секреты только в `<repo>/.env` и runtime в `<repo>/.gpu-rent/` (оба в `.gitignore`).

Опционально wizard (после того как `.env` хотя бы частично заполнен):

```powershell
.\gpu-rent.ps1 setup
```

Спросит (нумерованные меню): LLM runtime → пресет моделей → local-watchdog. Можно пропустить и настроить позже (`LLM_RUNTIME` / `up`).

Для разработки / pytest:

```powershell
python -m venv .venv
.\.venv\Scripts\activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
python -m gpu_rent --help
```

---

## 2. Selectel: проект и квота GPU

На новых аккаунтах лимит GPU часто **0**. Без поднятия лимита `up` не создаст сервер — это нормально, не баг CLI.

### 2.1. Проект

1. Панель → **IAM** → **Projects** (Проекты).
2. Отдельный проект, например `gpu-rent` (не общий «мусорный»).
3. Скопируй **ID проекта** (uuid) → это `OS_PROJECT_ID`.
4. **Номер аккаунта** (правый верхний угол) → это `OS_USER_DOMAIN_NAME`.

### 2.2. Есть ли GPU в квоте

1. **IAM** → **Projects** → твой проект → **Quotas and limits** / **Квоты** → **Cloud platform**.
2. Пул и сегмент с GPU: матрица [GPU availability](https://docs.selectel.ru/en/cloud-servers/create/gpus/). Часто смотрят мультизональный `ru-6` и `ru-7`.
3. Строка **GPU**. Если лимит 0 — тикет (ниже).

Лимит GPU поднимает **только поддержка**. Внутри уже выданного лимита квоту можно крутить в панели.

Подсказка по пулу после появления ключей: `.\gpu-rent.ps1 flavors` (скан `SCAN_POOLS`).

### 2.3. Тикет в поддержку

**Тикеты** в панели. Лимит увеличивают **на один конкретный проект**.

```text
Прошу увеличить лимит GPU в облачной платформе.

Проект: <имя> (ID: <uuid проекта>)
Пул / сегмент: ru-7 / ru-7a   ← подставь свой из матрицы GPU
Нужно: 1× NVIDIA RTX 4090 24 GB (если нет — ближайший аналог: 4090 48 GB или A5000).
Цель: один прерываемый (preemptible) облачный сервер для персональных сессий, диски сетевые.

Сейчас квота/лимит GPU = 0, создать сервер с GPU нельзя.
```

Пока тикет открыт, можно уже заполнять `.env` и гонять `doctor` — он покажет «квота 0».

---

## 3. Ключи OpenStack

Нужен **сервисный пользователь** + пароль. Не используй: Профиль → Access → API Keys → `X-Token`.

### 3.1. Сервисный пользователь

Только владелец аккаунта или `iam.admin`. На балансе для роли `member` обычно нужно хотя бы **~100 ₽**.

1. **IAM** → **Service users** / **Сервисные пользователи** → **Add**.
2. Имя, например `gpu-rent-api`.
3. Пароль: **≥ 20 символов**, сохрани сразу — потом только сброс.
4. Scope: **Projects** → проект `gpu-rent` → роль **`member`** (`reader` для `up` мало).
5. **Add user**.

Официально: [Add user](https://docs.selectel.ru/en/access-control/manage/add-user/), [API auth](https://docs.selectel.ru/en/api/authorization/).

### 3.2. RC-файл

1. **IAM** → **Service users** → пользователь → **Access**.
2. **RC files**: проект `gpu-rent`, локация = **пул** (например `ru-7`, не сегмент `ru-7a`) → **Download**.
3. Из `rc.sh` перенеси в `.env`:

| Переменная | Откуда |
| --- | --- |
| `OS_AUTH_URL` | обычно `https://cloud.api.selcloud.ru/identity/v3` |
| `OS_USER_DOMAIN_NAME` | номер аккаунта |
| `OS_PROJECT_ID` | uuid проекта |
| `OS_USERNAME` | имя сервисного пользователя |
| `OS_PASSWORD` | пароль (в RC часто нет — допиши сам) |
| `OS_REGION_NAME` | пул, например `ru-7` |
| `GPU_RENT_AZ` | **сегмент**, например `ru-7a` (в RC может не быть) |

Официально: [Configure OpenStack CLI](https://docs.selectel.ru/en/cloud-servers/tools/openstack-cli/configure-openstack-cli/).

### 3.3. Заполнить `.env`

```powershell
copy env.example .env
notepad .env
```

Вставь значения из RC + пароль + `GPU_RENT_AZ`. **Не коммить** `.env`.

Проверка: `.\gpu-rent.ps1 doctor` (не обязательно ставить `openstack` CLI).

---

## 4. Civitai API token (модели)

Нужен, если хочешь seed по `models.yaml`. Без токена SwarmUI поставит свою дефолтную модель — это нормально.

1. Войди на [civitai.com](https://civitai.com) (тот же аккаунт, что для `.red`).
2. [Account settings](https://civitai.com/user/account) → **API Keys** → **Add**.
3. Токен показывают **один раз** → в `.env`: `CIVITAI_API_TOKEN=...`
4. Хост по умолчанию **`civitai.red`** (полный каталог). С `.com` NSFW часто 404.
5. На `up` токен уходит и в seed на VM, и в SwarmUI User Settings (Civitai API Key) — вручную в UI вводить не нужно.
5. Манифест:

```powershell
copy models.example.yaml models.yaml
```

В URL нужен **`modelVersionId=`**, не id карточки модели. Подробности: [models.md](models.md).

---

## 5. Git-токен (только приватные репы)

Публичные репы в `extensions.yaml` клонируются без токена.

Приватные: GitHub fine-grained PAT, **Contents: Read** → `GIT_TOKEN` в `.env`.  
Шаблон: `extensions.example.yaml` → `extensions.yaml`. Пустой файл = стоковый SwarmUI. См. [extensions.md](extensions.md).

---

## 6. Чеклист перед `doctor`

- [ ] Python 3.11+, лаунчер отвечает на `--help`
- [ ] Проект Selectel, uuid скопирован
- [ ] Лимит GPU ≥ 1 (или тикет в работе — тогда `doctor` честно скажет «0»)
- [ ] Сервисный пользователь `member`, пароль сохранён
- [ ] RC с того же **пула**, где GPU
- [ ] `.env`: `OS_*` + `GPU_RENT_AZ`, не `X-Token`
- [ ] (опц.) Civitai + `models.yaml`
- [ ] На балансе хватает на **диск ~100 GB 24/7**, даже когда GPU выключен

```powershell
.\gpu-rent.ps1 doctor
.\gpu-rent.ps1 flavors
.\gpu-rent.ps1 dry-run
```

| Результат | Что делать |
| --- | --- |
| exit 0 | можно `up` |
| exit 1 | читай отчёт: чаще всего квота GPU = 0 или неверный пароль / пул |

---

## 7. Первый `up`

Первый прогон долгий (образ, SwarmUI, Comfy, seed): ориентир **20–40 минут**. Не закрывай терминал посередине bootstrap.

Без вопросов (CI / двойной клик):

```powershell
.\gpu-rent.ps1 up --yes
```

Интерактивно (меню LLM, пресет, **flavor / диск / preemptible**, confirm):

```powershell
.\gpu-rent.ps1 up
```

Что произойдёт:

1. Короткий doctor (полный — `up -v`).
2. Create/unshelve GPU + диски (после confirm).
3. Bootstrap SwarmUI, extensions, autocomplete, Civitai-seed, push локальных папок; optional LLM.
4. Туннель на `localhost:17801` (или LLM-порт), **проверка** что сервисы отвечают, access-card.
5. Процесс ждёт: **Ctrl+C** закрывает только туннель, GPU остаётся.

Полезные флаги:

| Флаг | Зачем |
| --- | --- |
| `--no-tunnel` | только облако; UI потом: `tunnel --open` |
| `--no-update` | не `git pull` SwarmUI/extensions |
| `--ollama` / `--llamacpp` | LLM рядом ([llm.md](llm.md)) |
| `--no-swarm` / `--llm-only` | только LLM, без SwarmUI (нужен runtime) |
| `--no-spot` | обычный (не preemptible) тариф |
| `--flavor ID` | явный flavor (пропускает меню flavor) |

Двойной клик без аргументов: в `gpu-rent.vars` задай `GPU_RENT_DEFAULT_ARGS=up --yes`. Сам `gpu-rent` без args показывает **help**, не поднимает GPU.

---

## 8. Закончить сессию

```powershell
.\gpu-rent.ps1 stop
```

Удаляет compute (+ FIP по умолчанию), **диски оставляет**. Модели на месте для следующего `up`.

| Команда | Эффект |
| --- | --- |
| `hold` / `hold --minutes 90` | отложить idle-killer |
| `status` | Nova, диск, killer, LLM |
| `destroy --i-understand-data-loss` | stop + удалить диски |

---

## Деньги и риски (кратко)

- **GPU** — пока жив compute.
- **Data-диск** — тарифицируется **всегда** после создания.
- Preemptible ~**24 ч** → `EXPIRED`; `tunnel` или `up` восстановят.
- Idle-killer: после льготы (~45 мин) + ~30 мин пустой очереди → delete compute.
- Цены в OpenStack API нет — смотри панель Selectel.

Дальше: чеклист живого прогона [spike-notes.md](spike-notes.md), справочник команд [cli.md](cli.md).