gpu-rent/docs/setup.md

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

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

Панель Selectel: 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».

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

.\gpu-rent.ps1 --help

gpu-rent.bat --help

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 хотя бы частично заполнен):

.\gpu-rent.ps1 setup

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

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

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. Часто смотрят мультизональный ru-6 и ru-7.
3. Строка GPU. Если лимит 0 — тикет (ниже).

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

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

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

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

Прошу увеличить лимит 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, API auth.

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.

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

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 (тот же аккаунт, что для .red).
2. Account settings → 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 вводить не нужно.
6. Манифест:

copy models.example.yaml models.yaml

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

---

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

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

Приватные: GitHub fine-grained PAT, Contents: Read → GIT_TOKEN в .env.
Шаблон: extensions.example.yaml → extensions.yaml. Пустой файл = стоковый SwarmUI. См. 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 выключен

.\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 / двойной клик):

.\gpu-rent.ps1 up --yes

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

.\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)
--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. Закончить сессию

.\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: после льготы (~90 мин) + ~60 мин пустой очереди → delete compute.
• Цены в OpenStack API нет — смотри панель Selectel.

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