Документация была переписана под версию 0.11: README, образ, первая машина, архитектура, требования, планы

README описывает продукт как простую замену Proxmox для дома: три способа установки
(ISO из GitHub Actions или make iso, одна команда, вручную), первую загрузку и мастер
настройки, возможности, страницу «Настройки», команды virtuality-ctl, обновления и откат,
удаление, диагностику и разработку. Упоминания Cockpit, консольного dashboard, тестовых
скриптов, эмуляции ARM64 на x86 и PXE убраны; таблица скриншотов сохранена и дополнена
существующими снимками.

docs/IMAGE.md — сборка ISO и все параметры image/build-iso.sh, вопросы установщика,
этапы первой загрузки, тема GRUB, артефакты CI, проверка и запись на флешку.
docs/FIRST_VM.md — первая машина только через панель: Ubuntu 26.04 из каталога
с cloud-init, Windows 11 с ISO, экран, проброс портов, снимки, резервные копии.
docs/ARCHITECTURE.md — текущее устройство: модули web/, virtuality-ctl, задачи,
службы systemd, TLS, firewall, сеть NAT с резервациями, хранилище, обновления.
docs/REQUIREMENTS.md — оборудование, ОС, ARM64, сеть, браузер.
docs/ROADMAP.md — что сделано в 0.11 и что планируется.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019LEUXMcdZo7b87mjkUsPgg

docs/ARCHITECTURE.md

@@ -1,122 +1,172 @@
 # Архитектура Virtuality
 
-Virtuality — это платформа виртуализации в стиле Proxmox, но с более компактной и контролируемой архитектурой.
-
-## Цель
-
-Создать собственную систему управления виртуальными машинами на базе стабильных Linux-компонентов:
-
-- KVM;
-- QEMU;
-- libvirt;
-- Cockpit на раннем этапе;
-- собственная веб-панель на следующих этапах.
-
-## Базовая схема
+Virtuality — одна нода: сервер с KVM/QEMU/libvirt, поверх которого работает панель на FastAPI. Панель не хранит собственную базу данных: источник правды о машинах — libvirt (`virsh`), о ноде — файлы в `/var/lib/virtuality/config`, о задачах — файлы в `/var/log/virtuality/operations`. Всё, что меняет сам сервер (службы, firewall, сеть, диски), делает один скрипт — `virtuality-ctl`, и панель вызывает его же.
 
 ```text
-Веб-интерфейс
-  ↓
-Backend API
-  ↓
-Node services
-  ↓
-libvirt / QEMU / KVM
-  ↓
-Host OS / Storage / Network
+Браузер
+  │  HTTP 8088 / HTTPS 8443
+  ▼
+virtuality-web.service — uvicorn, web/app.py (FastAPI, Jinja2)
+  ├── web/features/*        мастер, настройки, снимки, копии, загрузки, операции с машиной
+  ├── web/core.py           общие примитивы, хранилище задач
+  ├── web/nodectl.py ───────► /usr/local/bin/virtuality-ctl (systemd, TLS, ufw, br0, диск, пароль)
+  ├── web/network_core.py ──► virsh net-*, nft, ufw, iptables (сеть NAT и пробросы)
+  └── virsh / virt-install / virt-clone / qemu-img ──► libvirtd ──► QEMU/KVM
 ```
 
-## Слои системы
+---
 
-### 1. Web UI
+## Код панели: `web/`
 
-Будущая пользовательская панель Virtuality.
+| Модуль | Назначение |
+|---|---|
+| `app.py` | Основное приложение: вход, обзор, машины (создание, действия, ресурсы, порядок загрузки, привод), ISO и образы дисков (загрузка, конвертация, распаковка), сеть и пробросы, обновления, задачи, журналы, экран машины (WebSocket-прокси к VNC), `/healthz`. В конце подключает роутеры из `features/`. |
+| `core.py` | Общие примитивы: настройки из `.env`, сессии и авторизация (`require_auth`, `require_api_auth`, защита от cross-origin POST, ограничение попыток входа), `run_cmd`, `render` и окружение шаблонов, `valid_vm_name`, хранилище задач (`new_operation`, `run_operation`, `update_operation`, `finish_operation`, `active_operations_for`, `running_operations`, `interrupt_orphaned_operations`). Импорт `core` выставляет `LC_ALL=C.UTF-8`: вывод `virsh` разбирается панелью и не должен переводиться. |
+| `auth.py` | Проверка пароля Linux-пользователя по `/etc/shadow`: через `crypt`/`spwd`, а на Python 3.13+ — через `libcrypt` (ctypes). Ограничение попыток входа. |
+| `features/setup.py` | Мастер первичной настройки `/setup`: шаги install → welcome → account → access → network → storage → updates → finish, страница «Применяем настройки», ожидание перестройки сети в мост. |
+| `features/settings.py` | Страница «Настройки»: доступ (HTTPS/порт), пароль, часовой пояс, обновления, сеть машин, хранилище, перезагрузка/выключение, архив настроек, отчёт для поддержки. |
+| `features/snapshots.py` | Снимки: внутренние снимки libvirt (`virsh snapshot-*`), до 8 на машину, создание и возврат — фоновые задачи. |
+| `features/backups.py` | Резервные копии: `vm.xml` + копии дисков + `meta.json` в `backups/<машина>/<ГГГГММДД-ЧЧММ>/`; восстановление под тем же или новым именем; запуск как скрипта для расписания. |
+| `features/downloads.py` | Скачивание ISO и образов по ссылке и из каталога — фоновые задачи типа `download` с прогрессом, проверкой контрольной суммы и отменой. |
+| `features/vmops.py` | Увеличение диска, клонирование (`virt-clone`), пауза, спящий режим (`virsh managedsave`), заметки (title/description машины), живая нагрузка (`virsh domstats`). |
+| `nodectl.py` | Факты о ноде (сеть, диски, оборудование, часовые пояса, состояние первой загрузки, выбор мастера) и действия через `virtuality-ctl`. Действия, которые перезапускают панель, запускаются отложенно через `systemd-run`. |
+| `network_core.py` | Сеть NAT `virtuality-nat`, резервации DHCP, пробросы портов и их применение (nftables, ufw, iptables). |
+| `catalog.py` | Каталог облачных образов (Ubuntu 26.04/24.04, Debian 13, Alpine 3.23 для x86_64 и aarch64) и типы ОС для установки с ISO (`osinfo` для `virt-install`). |
+| `cloudinit.py` | Seed cloud-init для машин из готовых образов: `user-data` (пользователь, хеш пароля SHA-512, SSH-ключи, рост диска, гостевой агент) и `meta-data`; подключается к `virt-install --cloud-init`. |
+| `host_profile.py` | Профиль сервера (`x86_64`, `raspberry-arm64`, `orangepi5-arm64`, `generic-arm64`), проверки готовности; хранится в `config/host_profile.json`. |
+| `update_core.py` | Проверка обновлений: канал, целевой ref, список пропущенных версий из `updates/versions.json`, запуск `scripts/apply_github_update.sh` через `systemd-run`. |
+| `presenters.py` | Человеческие названия состояний, профили ресурсов машин, список типовых портов, форматирование размеров. |
+| `restore_network.py` | Повторное применение пробросов после загрузки (`virtuality-network.service`). |
+| `redirect_http.py` | Перенаправление HTTP → HTTPS на порту 8088, когда включён TLS (`virtuality-redirect.service`). |
+| `templates/`, `static/` | Jinja2-шаблоны (`base.html` — каркас, `_ui.html` — компоненты), `app.css` (светлая и тёмная темы), `panel.js`, шрифт и иконки. Панель не ходит в интернет. |
 
-Задачи:
+Правило для роутов модулей: POST-маршруты вида `/vm/{name}/<модуль>/<действие>` — минимум четыре сегмента, иначе их перехватит общий `@app.post("/vm/{name}/{action}")`.
 
-- список виртуальных машин;
-- создание VM;
-- управление питанием;
-- консоль;
-- хранилища;
-- сеть;
-- бэкапы;
-- пользователи и роли.
+### Фоновые задачи
 
-### 2. Backend API
+Долгие операции (создание машины, конвертация образа, скачивание, снимок, копия, клон, спящий режим) выполняются в потоках и записываются в `/var/log/virtuality/operations/<id>.json` (статус, прогресс, сообщение, метаданные) и `<id>.log` (журнал). Раздел «Задачи» и страницы машин читают эти файлы; `active_operations_for(vm, kinds)` защищает машину от двух одновременных операций. При старте панели `interrupt_orphaned_operations()` закрывает задачи, оставшиеся в состоянии «выполняется» после перезапуска. `virtuality-ctl maintenance` удаляет задачи старше 30 дней и оставляет не больше 300.
 
-Единая точка управления нодой.
+---
 
-Задачи:
+## Управление нодой: `scripts/virtuality-ctl`
 
-- принимать команды от Web UI;
-- валидировать действия;
-- работать с libvirt;
-- вести журнал событий;
-- отдавать состояние VM, storage и сети.
+Один bash-скрипт, устанавливается в `/usr/local/bin`. Панель (через `nodectl.py`) и администратор в терминале делают одно и то же:
 
-### 3. Node services
+- **`reconfigure`** — читает `/var/lib/virtuality/config/web.env` и пересоздаёт systemd-юниты, logrotate, `/etc/default/libvirt-guests`, правила ufw; переводит VNC старых машин на `127.0.0.1`; перезапускает панель.
+- **`set KEY=VALUE`** — проверяет и сохраняет настройку в `web.env`, затем `reconfigure` (для настроек обновления — только перезапись таймера).
+- **TLS** — при `VIRTUALITY_TLS=1` создаёт самоподписанный сертификат EC P-256 на 10 лет в `config/tls/panel.{key,crt}` (SAN: имя сервера, localhost, адрес), uvicorn слушает `VIRTUALITY_TLS_PORT` (8443), а `virtuality-redirect.service` перенаправляет с HTTP-порта.
+- **Мост `br0`** — `bridge <iface> [dhcp|static]` делает копию `/etc/netplan`, пишет `60-virtuality-br0.yaml`, проверяет `netplan generate`, взводит таймер `virtuality-netplan-revert` на 120 секунд и применяет; `bridge-confirm` снимает таймер, `bridge-revert` возвращает копию. Панель после перестройки сети сама вызывает подтверждение, когда снова получает ответ от сервера.
+- **`storage-use /dev/sdX`** — только пустой диск без разделов: `mkfs.ext4`, перенос текущего содержимого `/var/lib/virtuality`, запись в `/etc/fstab` (`nofail`), монтирование.
+- **`passwd`, `timezone`, `power`, `backup-config`, `restore-config`, `rollback`, `maintenance`, `support-bundle`, `uninstall`** — см. README.
 
-Системные сервисы Virtuality.
+Журнал действий: `/var/log/virtuality/virtuality-ctl.log`.
 
-Задачи:
+---
 
-- диагностика ноды;
-- обновления;
-- резервное копирование;
-- мониторинг;
-- фоновые задачи.
+## Службы systemd
 
-### 4. libvirt / QEMU / KVM
+Создаются `virtuality-ctl reconfigure`:
 
-Нижний слой виртуализации.
+| Юнит | Что делает |
+|---|---|
+| `virtuality-web.service` | Панель: `uvicorn app:app` от root из `/opt/virtuality/web` с venv `/opt/virtuality/venv`; `Restart=always`. |
+| `virtuality-redirect.service` | Только при TLS: HTTP → HTTPS. |
+| `virtuality-network.service` | При загрузке заново применяет пробросы портов (`restore_network.py`). |
+| `virtuality-auto-update.timer` / `.service` | Ночная проверка обновлений (`scripts/auto_update_check.sh`), 04:00 ± 30 минут; включён при `VIRTUALITY_AUTO_UPDATE=1`. |
+| `virtuality-maintenance.timer` / `.service` | Ежедневное обслуживание: старые задачи, временные файлы, недокачанные загрузки, `journalctl --vacuum-size=300M`, запись занятости диска в `config/health.json`. |
+| `libvirt-guests.service` | При выключении сервера машины выключаются корректно (`ON_SHUTDOWN=shutdown`, до 180 секунд), при загрузке не запускаются сами — только те, у кого включён автозапуск. |
 
-Задачи:
+Отдельно, из образа: `virtuality-firstboot.service` — первая загрузка (см. [IMAGE.md](IMAGE.md)); временные юниты `virtuality-netplan-revert` (автооткат моста), `virtuality-apply-*` (отложенное применение настроек) и `virtuality-update-*` (обновление вне cgroup панели, чтобы перезапуск панели не убил сам процесс обновления).
 
-- запуск виртуальных машин;
-- управление дисками;
-- управление сетевыми интерфейсами;
-- снапшоты;
-- консольный доступ.
+---
 
-### 5. Host OS
+## Безопасность панели
 
-Операционная система сервера.
+- Вход — по имени и паролю системного пользователя (`VIRTUALITY_AUTH_USER`); проверяется по `/etc/shadow`, поэтому панель работает от root. После 5 неверных паролей адрес блокируется на 5 минут; сессия (подписанная cookie, ключ в `config/session_secret`) живёт 12 часов.
+- POST-запросы принимаются только с того же origin; за reverse proxy нужно передавать исходный `Host` (и `Upgrade`/`Connection` для экрана машины).
+- Экран машины: VNC у всех машин слушает `127.0.0.1`, панель проксирует его в WebSocket по подписанному токену и только при действующей сессии. Порты 5900–5999 в ufw закрыты.
+- Пароль cloud-init хранится только как хеш SHA-512; секреты не попадают в журналы и отчёт для поддержки.
+- Firewall: `install_virtuality_node.sh` включает ufw и разрешает SSH; `virtuality-ctl` открывает только порт панели (и HTTPS-порт), список открытых портов хранит в `config/ports.state`.
 
-Целевые системы:
+---
 
-- Debian 12;
-- Ubuntu Server 22.04;
-- Ubuntu Server 24.04.
+## Сеть машин
 
-## Пути
+### NAT: `virtuality-nat`
+
+libvirt-сеть с мостом `virbr100`, подсеть `192.168.100.0/24`, шлюз `192.168.100.1`, DHCP `192.168.100.50–200`. Описание сохраняется в `/var/lib/virtuality/network/virtuality-nat.xml`. Создаётся мастером, страницей «Сеть и доступ» или автоматически при создании первой машины в режиме NAT. Включается `net.ipv4.ip_forward` (`/etc/sysctl.d/99-virtuality-forward.conf`) и ослабляется rp_filter (`98-virtuality-rpfilter.conf`).
+
+**Постоянные адреса.** Для каждой машины MAC-адрес вычисляется из её имени (`stable_mac`), и в сети создаётся резервация DHCP (`virsh net-update add ip-dhcp-host`) — машина всегда получает один и тот же адрес, панель знает его ещё до первого запуска. При удалении машины резервация освобождается.
+
+**Пробросы портов** хранятся в `/var/lib/virtuality/network/port_forwards.json` и применяются тремя способами сразу, чтобы работать на любом дистрибутиве:
+
+1. nftables — таблица `ip virtuality` в `/etc/virtuality/nftables/virtuality.nft` (DNAT, forward, masquerade);
+2. ufw — правила `route allow`, список сохранённых правил в `network/ufw_rules.json`;
+3. iptables — запасной вариант, все правила помечены комментарием `virtuality-forward`, чтобы их можно было найти и удалить.
+
+Адрес машины определяется через гостевой агент, `virsh domifaddr`, аренды DHCP по MAC машины, либо задаётся вручную. «Проверить» рядом с правилом делает TCP-подключение к машине и показывает команды для диагностики.
+
+### Домашняя сеть: мост `br0`
+
+Сервер объединяет свой проводной интерфейс в мост `br0` (netplan), машины подключаются к нему и получают адреса от роутера. Wi-Fi в мост объединить нельзя — тогда доступен только NAT. Как устроен автооткат — выше, в разделе про `virtuality-ctl`.
+
+---
+
+## Хранилище
 
 ```text
-/opt/virtuality                 # код и конфигурация проекта
-/var/lib/virtuality             # runtime-хранилище
-/var/lib/virtuality/iso         # ISO-образы
-/var/lib/virtuality/images      # диски VM
-/var/lib/virtuality/backups     # резервные копии
-/var/log/virtuality             # логи
+/var/lib/virtuality/
+├── iso/            установочные образы; libvirt-пул virtuality-iso
+├── images/         диски машин <имя>.qcow2; libvirt-пул virtuality-images
+├── disk-images/    готовые образы систем (каталог, ссылки, загрузки с компьютера)
+├── backups/        резервные копии машин (<машина>/<ГГГГММДД-ЧЧММ>/) и архивы настроек config-*.tar.gz
+├── config/         web.env, setup.json, setup_done, wizard.json, host_profile.json,
+│                   session_secret, ports.state, health.json, tls/, netplan-backup/
+├── network/        port_forwards.json, ufw_rules.json, virtuality-nat.xml
+├── update/         state.json, last_check.json, временные файлы обновления
+└── tmp/            загрузки (.<имя>.part, .<имя>.uploading), seed cloud-init; TMPDIR панели
 ```
 
-## Принципы
+Мастер и «Настройки» умеют отдать под всё это отдельный пустой диск — он монтируется в `/var/lib/virtuality` целиком. Память «спящих» машин libvirt хранит в `/var/lib/libvirt/qemu/save`.
 
-- исходный код отдельно от runtime-данных;
-- диски VM и ISO не хранятся в Git;
-- конфиги должны быть прозрачными;
-- установщик должен быть повторяемым;
-- сетевые изменения делаются осторожно, чтобы не уронить SSH;
-- архитектура документируется до активной разработки.
+Код и служебные файлы:
 
-## Этап v0.1
+```text
+/opt/virtuality/source        git-репозиторий, из него ставится панель и берутся обновления
+/opt/virtuality/web           установленная панель (+ .env с пользователем и ключом сессий)
+/opt/virtuality/web.prev      предыдущая версия для virtuality-ctl rollback
+/opt/virtuality/venv          virtualenv
+/opt/virtuality/virtuality.env  пути ноды (пишет install_virtuality_node.sh)
+/etc/virtuality/image.env     параметры образа (только после установки с ISO)
+/etc/virtuality/nftables/     правила пробросов
+/var/log/virtuality/          firstboot.log, update.log, virtuality-ctl.log, install_*.log, operations/
+```
 
-На этапе v0.1 создаётся фундамент:
+---
 
-- установщик ноды;
-- установка KVM/QEMU/libvirt;
-- установка Cockpit;
-- storage pools;
-- структура проекта;
-- GitHub-синхронизация;
-- базовая диагностика.
+## Обновления
+
+1. **Канал** (`VIRTUALITY_UPDATE_CHANNEL` в `web.env`): `stable` — последний тег `vX.Y.Z` (пока тегов нет — ветка `main`); `main` — ветка `main`. Логика одна и та же в `web/update_core.py` и `scripts/update_target.sh`.
+2. **Проверка** (`/update/check`, ночной `scripts/auto_update_check.sh`): `git fetch --tags`, сравнение текущего коммита с целевым; обновление предлагается, только если целевой коммит — потомок текущего (нода никогда не откатывается сама). Список изменений берётся из `updates/versions.json` целевой версии.
+3. **Применение** (`scripts/apply_github_update.sh`, запускается через `systemd-run`): `git checkout -B main <цель>` и `git clean`; если git недоступен — скачивание ZIP-архива с GitHub и `rsync`; затем `scripts/install_web_panel.sh` (панель копируется в `web.new`, старая переименовывается в `web.prev`, venv обновляется) и `systemctl restart virtuality-web`. Состояние — `/var/lib/virtuality/update/state.json`, журнал — `/var/log/virtuality/update.log`.
+4. **Откат**: `virtuality-ctl rollback` меняет местами `web` и `web.prev`.
+
+Установщики и скрипты вне `web/`:
+
+```text
+install.sh                          установка одной командой (проверки, пакеты, пользователь, клон, три установщика ниже)
+install_virtuality_node.sh          пакеты KVM/QEMU/libvirt (x86_64 или ARM64), пулы, ufw, группы пользователя
+scripts/install_web_panel.sh        панель, venv (офлайн из wheels/ при наличии), virtuality-ctl, юниты
+scripts/install_healthcheck_command.sh   команда vhealth (scripts/virtuality_healthcheck.sh)
+scripts/detect_host_profile.sh      профиль сервера для установщика
+scripts/virtuality_firstboot.sh     первая загрузка после ISO
+scripts/auto_update_check.sh, apply_github_update.sh, update_target.sh   обновления
+scripts/bump_patch_version.py       поднять patch-версию в VERSION
+image/build-iso.sh, autoinstall.yaml, files/, grub/   сборка ISO
+```
+
+---
+
+## Тесты и CI
+
+`tests/conftest.py` подменяет `run_cmd`, так что `virsh`, `systemctl`, `qemu-img` и остальные команды имитируются — тесты идут на любой машине без libvirt. `tests/dev_server.py` поднимает демо-панель с теми же подменами. `make check` = pyflakes + shellcheck + pytest; `.github/workflows/ci.yml` запускает это на Python 3.11–3.14, `.github/workflows/image.yml` собирает ISO.

docs/FIRST_VM.md

@@ -1,104 +1,138 @@
-# Первая тестовая виртуальная машина
+# Первая виртуальная машина
 
-Этот документ фиксирует проверку первого рабочего сценария Virtuality: сеть `br0`, libvirt storage pools и запуск тестовой VM.
+Всё в этом документе делается через панель в браузере — терминал не понадобится. Считаем, что Virtuality установлена и мастер настройки пройден (см. README).
 
-## Требования
+Сначала — самый быстрый путь: готовая Ubuntu за минуту. Потом — установка Windows 11 с ISO, экран машины, доступ снаружи, снимки и резервные копии.
 
-Перед созданием VM должны быть готовы:
+---
 
-- KVM/QEMU;
-- libvirt;
-- Cockpit;
-- storage pools `virtuality-images` и `virtuality-iso`;
-- bridge `br0`;
-- default route через `br0`.
+## 1. Быстрая машина из каталога: Ubuntu Server 26.04
 
-Проверка:
+Готовые (облачные) образы — это уже установленная система без пароля. Панель скачивает образ, делает из него диск нужного размера и через cloud-init настраивает первый вход: пользователя, пароль, SSH-ключ.
+
+### Скачать образ
+
+1. Откройте **Образы ОС** → вкладка **Готовые системы**.
+2. В карточке **Каталог готовых систем** найдите **Ubuntu Server 26.04 LTS** (помечена «Рекомендуем») и нажмите **Скачать**. Сервер скачает образ с сайта Ubuntu сам и проверит контрольную сумму; ход виден в **Задачах** и на этой же странице.
+3. Когда образ отмечен «Загружен», рядом появится кнопка **Создать машину** — она открывает мастер с уже выбранным образом.
+
+В каталоге также Ubuntu Server 24.04 LTS, Debian 13 и Alpine Linux 3.23. Свой образ (`.qcow2`, `.img`, `.raw`, `.img.xz`) можно загрузить с компьютера перетаскиванием или скачать по ссылке в карточке **Скачать по ссылке**.
+
+### Создать машину
+
+Шаг **1. Название и система**:
+
+- **Название машины** — латиница, цифры, точка, дефис, подчёркивание (например, `ubuntu-1`). Это же имя станет именем компьютера внутри системы.
+- Источник **Готовая система** уже выбран, образ подставлен.
+- Переключатель **Настроить первый вход** должен быть включён: у готовых образов нет пароля, без этого шага в машину не войти.
+  - **Пользователь** — панель подставляет стандартного пользователя образа (`ubuntu`, у Debian — `debian`, у Alpine — `alpine`); можно указать свой. Он получит права администратора (`sudo`).
+  - **Пароль** — не короче 6 символов.
+  - **SSH-ключ** — необязательно; вставьте содержимое `~/.ssh/id_ed25519.pub`. Если указать только ключ без пароля, вход по SSH будет только по ключу.
+
+Шаг **2. Мощность**: выберите профиль — **Мини** (1 ядро, 1 ГБ, 10 ГБ), **Стандарт** (2 ядра, 4 ГБ, 40 ГБ), **Мощная** (4 ядра, 8 ГБ, 80 ГБ) — или задайте ядра, память и диск сами. Диск образа увеличивается до выбранного размера, а система при первой загрузке сама расширит файловую систему.
+
+Шаг **3. Сеть**: **Автоматически** — машина получит постоянный адрес `192.168.100.x` в отдельной сети и выйдет в интернет через сервер; снаружи её не видно, пока вы не откроете доступ. **В локальной сети** (если в мастере настройки выбран мост) — машина станет устройством вашей домашней сети и получит адрес от роутера.
+
+Справа в **Итого** проверьте сводку и нажмите **Создать машину**. Панель откроет страницу задачи с живым журналом. Обычно в пределах минуты появится «Машина создана. Вход: ubuntu по паролю. Адрес в сети машин: 192.168.100.x».
+
+### Войти
+
+Откройте страницу машины (из **Обзора**) → **Открыть экран** и войдите с указанными пользователем и паролем. В машину сразу ставится гостевой агент, поэтому её адрес виден на странице машины и в **Сети и доступе** — по нему можно зайти по SSH из локальной сети (если выбран мост) или после проброса порта (см. ниже).
+
+---
+
+## 2. Windows 11 с установочного ISO
+
+### Загрузить ISO
+
+1. Скачайте ISO Windows 11 с сайта Microsoft на свой компьютер.
+2. **Образы ОС** → вкладка **Установочные образы** → перетащите файл в окно загрузки. Или вставьте прямую ссылку на `.iso` в карточку **Скачать по ссылке** — сервер скачает его сам.
+
+### Создать машину
+
+1. **Создать машину** → шаг 1: название (например, `win11`), источник **Установить с диска**, выберите ISO.
+2. **Что будете устанавливать** → **Windows 11 / Server 2025**. Панель сама включит UEFI и виртуальный TPM 2.0 (без него Windows 11 отказывается ставиться), подберёт диск SATA и сетевую карту Intel — драйверы во время установки не нужны.
+3. Шаг 2: профиль **Мощная** (4 ядра, 8 ГБ, 80 ГБ) — Windows 11 требует минимум 4 ГБ памяти и 64 ГБ диска.
+4. Шаг 3: сеть — как и для Linux.
+5. **Создать машину**. Задача завершится за несколько секунд — машина создана и запущена с установочного диска.
+
+### Установить систему
+
+1. На странице машины нажмите **Открыть экран**. Сразу после запуска Windows показывает «Press any key to boot from CD or DVD» — нажмите любую клавишу в окне экрана, иначе загрузка с диска пропустится. Если пропустили — **Перезагрузить** на странице машины и попробовать снова.
+2. Дальше установка идёт как на обычном компьютере. Диск в установщике будет пустым — выберите его целиком.
+3. После установки на странице машины откройте вкладку **Диски и загрузка** → **Привод CD/DVD** и извлеките установочный образ, чтобы машина больше не предлагала загрузку с него.
+
+Для других систем выбирайте тип **Linux** (Ubuntu, Debian, Fedora и другие), **Windows 10 / Server 2019–2022** (классическая загрузка) или **Другая система**.
+
+---
+
+## 3. Экран машины
+
+- Кнопка **Открыть экран** на странице машины открывает экран в новой вкладке браузера — это как монитор, подключённый к машине. Работает и для установки системы, и когда сеть внутри машины ещё не настроена.
+- Если курсор «застрял» внутри экрана, нажмите **Ctrl + Alt**.
+- Экран доступен только через панель: VNC-порты машин наружу не открываются, соединение идёт через сервер по вашей сессии.
+- Для повседневной работы удобнее подключаться по SSH (Linux) или по удалённому рабочему столу (Windows) — как открыть к ним доступ, ниже.
+
+---
+
+## 4. Доступ к машине снаружи (проброс портов)
+
+В сети **Автоматически (NAT)** машины не видны ни из домашней сети, ни из интернета, пока вы не откроете нужный порт на сервере.
+
+1. Откройте **Сеть и доступ** → карточка **Открыть доступ**.
+2. **Машина** — выберите машину (рядом показан её адрес).
+3. **Что открыть** — сервис из списка: **SSH — удалённый доступ к Linux**, **Сайт (HTTP)**, **Сайт (HTTPS)**, **Удалённый рабочий стол Windows (RDP)**, **Minecraft**, MySQL, PostgreSQL, OpenVPN, WireGuard и другие — или **Другой порт**.
+4. **Порт в машине** заполнится сам (для SSH — `22`), **Порт на сервере** — например, `2222`. Протокол TCP или UDP подставляется по сервису. Можно указать диапазон вида `10000-20000`.
+5. Нажмите **Открыть доступ**. Теперь `адрес-сервера:2222` ведёт в машину:
+
+   ```bash
+   ssh ubuntu@адрес-сервера -p 2222
+   ```
+
+   Для Windows выберите **RDP** и подключайтесь приложением «Подключение к удалённому рабочему столу» по адресу `адрес-сервера:3389` (или другому порту сервера, который вы указали).
+
+Кнопка **Проверить** рядом с правилом покажет, доходит ли трафик до машины и слушает ли она порт. Правила восстанавливаются после перезагрузки сервера сами. Чтобы сервис был доступен из интернета, дополнительно пробросьте тот же порт на роутере на адрес сервера.
+
+Адреса в сети NAT закреплены за машинами по имени, поэтому пробросы не ломаются после перезагрузок. Если адрес машины не определился (например, система внутри ещё не запущена), в карточке **Адреса машин** его можно указать вручную.
+
+Машинам в режиме **В локальной сети** проброс не нужен: у них свой адрес от роутера, как у ноутбука или телефона.
+
+---
+
+## 5. Снимок перед рискованными изменениями
+
+Снимок — точка восстановления машины: перед обновлением системы, экспериментом с настройками или установкой сомнительной программы.
+
+1. Страница машины → вкладка **Снимки** → карточка **Создать снимок**, при желании впишите описание («перед обновлением») → **Создать снимок**.
+2. У работающей машины в снимок попадает и память — она на несколько секунд замрёт, зато вернётся ровно в то же состояние с открытыми программами. У выключенной сохраняется только диск.
+3. Если что-то пошло не так — **Вернуться** рядом с нужным снимком. Машина откатится к тому моменту; всё, что сделано после снимка, пропадёт.
+4. Ненужные снимки удаляйте: они занимают место внутри диска машины. На одну машину — до 8 снимков.
+
+Ограничения: снимки работают только с дисками qcow2 (все машины, созданные панелью, такие). Для машин с UEFI-прошивкой (Windows 11, образы Alpine, все машины на ARM64) внутренние снимки в текущей версии libvirt недоступны — панель предупредит; для них используйте резервные копии.
+
+---
+
+## 6. Резервная копия
+
+Резервная копия — полная копия настроек машины и всех её дисков в отдельной папке на сервере. В отличие от снимка, она не зависит от диска машины и переживёт его повреждение.
+
+1. Страница машины → вкладка **Резервные копии** → **Создать копию** (заметка по желанию). Работающая машина будет корректно выключена, скопирована и запущена снова — в списке машин в это время видно, что происходит.
+2. Копии всех машин собраны в разделе **Резервные копии**; они лежат в `/var/lib/virtuality/backups/<машина>/<дата-время>/`. Ход создания виден в **Задачах**, страницу можно закрыть.
+3. **Восстановить**: выберите копию → укажите название — то же (тогда текущую машину придётся заменить, панель попросит подтверждение) или новое (получите вторую машину рядом с первой). Восстановленная машина создаётся выключенной. Файлы копии остаются на месте, восстанавливать из неё можно сколько угодно раз.
+4. Перед восстановлением панель проверяет, хватит ли места в `/var/lib/virtuality`.
+
+Копию можно делать и по расписанию из терминала сервера — например, задачей cron:
 
 ```bash
-sudo vhealth
-ip -br a
-ip route
-virsh pool-list --all
+sudo /opt/virtuality/venv/bin/python /opt/virtuality/web/features/backups.py web01 "ночная копия"
 ```
 
-Нормальная сеть:
+---
 
-```text
-enp2s0  UP
-br0     UP  10.0.0.200/24
-default via 10.0.0.1 dev br0
-```
+## Что дальше
 
-## Создание тестовой VM
-
-```bash
-cd ~/virtuality
-git pull
-sudo bash scripts/create_test_vm.sh
-```
-
-По умолчанию создаётся VM:
-
-```text
-Name:   test-alpine
-RAM:    1024 MB
-CPU:    1 vCPU
-Disk:   8 GB qcow2
-ISO:    Alpine Linux
-Network: br0
-Graphics: VNC
-```
-
-Можно задать имя:
-
-```bash
-sudo bash scripts/create_test_vm.sh test-alpine-2
-```
-
-## Проверка
-
-```bash
-virsh list --all
-sudo virsh vncdisplay test-alpine
-sudo vhealth
-```
-
-Если `vncdisplay` показывает `:0`, значит порт VNC — `5900`.
-
-Если показывает `:1`, значит порт VNC — `5901`.
-
-## Доступ через Cockpit
-
-Открыть:
-
-```text
-https://SERVER_IP:9090
-```
-
-Дальше:
-
-```text
-Virtual machines → test-alpine → Console
-```
-
-## Что считается успешным результатом
-
-Этап считается пройденным, если:
-
-- VM появилась в `virsh list --all`;
-- VM запущена;
-- консоль открывается в Cockpit или через VNC;
-- VM подключена к bridge `br0`;
-- `sudo vhealth` не показывает критических ошибок по Virtuality.
-
-## Следующий этап
-
-После первой тестовой VM можно переходить к разработке собственной панели управления Virtuality:
-
-- список VM;
-- статусы VM;
-- запуск/остановка;
-- просмотр storage pools;
-- создание VM через UI;
-- базовый журнал событий.
+- **Клонировать** (меню на странице машины) — точная копия с новым именем и своим адресом, удобно для тестов.
+- **Спящий режим** — сохранить память на диск и выключить; после запуска машина продолжит с того же места.
+- **Автозапуск** — переключатель на странице машины: машина включится сама после перезагрузки сервера.
+- **Ресурсы** — процессор и память можно поменять, когда машина выключена; диск — увеличить в любой момент во вкладке **Диски и загрузка**.
+- Раздел **Помощь** в панели повторяет главное из этого документа.

docs/IMAGE.md

@@ -1,54 +1,38 @@
 # Установочный образ Virtuality
 
-Virtuality можно поставить двумя способами:
+Загрузочный ISO ставит Virtuality на чистый сервер «с нуля», как Proxmox: записали на флешку, загрузились, ответили на три экрана — после перезагрузки панель уже открыта в браузере, а мастер настройки показывает, как ставятся остальные компоненты.
 
-1. **Скрипт на готовый сервер** — `curl ... install.sh | bash` (см. README).
-2. **Установочный ISO** — загрузочный образ «с нуля», как у Proxmox: записываете на флешку, загружаетесь, отвечаете на 3 экрана, после перезагрузки получаете готовую ноду.
-
-Этот документ про второй способ.
-
----
-
-## Что внутри образа
-
-Образ собирается из официального, ничем не изменённого **Ubuntu Server 26.04 LTS live-server ISO** (amd64 или arm64; поддержка до 2031 года) и дополняется:
+Образ собирается из официального, ничем не изменённого **Ubuntu Server 26.04 LTS live-server ISO** (amd64 или arm64) и дополняется:
 
 ```text
-/autoinstall.yaml                      # сценарий установщика Ubuntu (subiquity autoinstall)
-/virtuality/source                     # исходники Virtuality (git-репозиторий нужной версии)
-/virtuality/source/wheels              # Python-колёса web-панели для офлайн-установки
-/virtuality/image.env                  # параметры сборки: порт панели, автообновление, пользователь
-/virtuality/virtuality-firstboot.service
-/boot/grub/grub.cfg                    # меню «Install Virtuality X.Y.Z»
+/autoinstall.yaml                          # сценарий установщика Ubuntu (subiquity autoinstall)
+/virtuality/source                         # исходники Virtuality нужной версии (git-репозиторий)
+/virtuality/source/wheels                  # Python-колёса панели и pip — для установки без интернета
+/virtuality/image.env                      # параметры сборки: версия, порт панели, автообновление
+/virtuality/virtuality-firstboot.service   # служба первой загрузки
+/boot/grub/grub.cfg                        # меню «Установить Virtuality X.Y.Z» с фирменной темой
+/boot/grub/themes/virtuality/              # тема GRUB
 ```
 
 Загрузочные записи BIOS и UEFI берутся из оригинального ISO без изменений.
 
-## Как проходит установка
+---
 
-1. Загрузка с ISO → пункт **Install Virtuality**.
-2. Установщик Ubuntu спрашивает только **сеть**, **диск** и **пользователя** (имя, пароль, hostname). Язык, раскладка, SSH-сервер и остальное заданы автоматически.
-3. Установщик копирует Virtuality в `/opt/virtuality/source` и включает `virtuality-firstboot.service`.
-4. После перезагрузки `virtuality-firstboot` (нужен интернет) ставит KVM/QEMU/libvirt, Cockpit, web-панель, `vhealth` и консольный dashboard. Обычно это 5–15 минут. Если сети нет или apt упал, попытка повторяется каждую минуту до успеха.
-5. Готово:
+## Где взять готовый образ
 
-```text
-Web-панель: http://SERVER_IP:8088   (логин — пользователь, созданный в установщике)
-Cockpit:    https://SERVER_IP:9090
-```
+Workflow `.github/workflows/image.yml` собирает ISO в GitHub Actions:
 
-Адрес панели также показывается на экране входа консоли. Ход первой настройки:
+- автоматически при выпуске — пуш тега `v*` (amd64 и arm64);
+- при pull request, который меняет `image/**`, `scripts/virtuality_firstboot.sh`, `web/requirements.txt` или сам workflow;
+- вручную: Actions → **Build ISO image** → Run workflow → архитектура `amd64`, `arm64` или `both`.
 
-```bash
-sudo journalctl -fu virtuality-firstboot
-cat /var/log/virtuality/firstboot.log
-```
+После сборки workflow проверяет, что в образе есть загрузочная запись UEFI, `autoinstall.yaml` разбирается как YAML, а в `grub.cfg` есть пункт Virtuality. Образы Ubuntu Server больше лимита GitHub Releases (2 ГБ на файл), поэтому ISO публикуются как **artifacts** запуска (`virtuality-iso-amd64`, `virtuality-iso-arm64`) и хранятся 30 дней. В артефакте — `.iso` и `.sha256`.
 
 ---
 
-## Сборка ISO
+## Сборка своими руками
 
-Нужна Linux-машина (root не нужен), ~10 GB свободного места и пакеты:
+Нужна Linux-машина (root не нужен), около 10 ГБ свободного места и пакеты:
 
 ```bash
 sudo apt install -y xorriso git curl python3-pip
@@ -63,81 +47,154 @@ make iso                 # amd64
 make iso ARCH=arm64      # ARM64-серверы с UEFI
 ```
 
-Скрипт сам скачает последний Ubuntu 26.04.x live-server ISO, проверит SHA256 и положит результат в `dist/`:
+`image/build-iso.sh` сам находит последний Ubuntu 26.04.x live-server ISO, скачивает его (около 3 ГБ), проверяет SHA256 и кладёт результат в `dist/`:
 
 ```text
-dist/virtuality-0.10.0-ubuntu-26.04-amd64.iso
-dist/virtuality-0.10.0-ubuntu-26.04-amd64.iso.sha256
+dist/virtuality-0.11.0-ubuntu-26.04-amd64.iso
+dist/virtuality-0.11.0-ubuntu-26.04-amd64.iso.sha256
 ```
 
-Скачанный ISO Ubuntu кешируется в `.cache/iso`. Уже скачанный образ можно передать явно:
+Скачанный ISO Ubuntu кешируется в `.cache/iso` (или в `VIRTUALITY_ISO_CACHE`). Уже скачанный образ можно передать явно:
 
 ```bash
 ./image/build-iso.sh --ubuntu-iso ~/Downloads/ubuntu-26.04.1-live-server-amd64.iso
 ```
 
-### Параметры
+### Параметры `image/build-iso.sh`
 
 ```text
---arch amd64|arm64         архитектура
+--arch amd64|arm64         архитектура (по умолчанию amd64)
 --ubuntu 26.04|24.04       база образа (по умолчанию 26.04 LTS)
+--ubuntu-iso PATH          использовать локальный live-server ISO вместо скачивания
+--cache-dir DIR            где хранить скачанные ISO Ubuntu (по умолчанию .cache/iso)
+--output DIR               куда класть результат (по умолчанию dist)
 --ref GIT_REF              какую версию Virtuality положить в образ (по умолчанию HEAD)
---web-port PORT            порт web-панели (по умолчанию 8088)
---no-auto-update           не включать ночное автообновление с GitHub
---locale / --keyboard / --timezone
+--repo-url URL             откуда установленная нода будет получать обновления
+--web-port PORT            порт панели на установленной ноде (по умолчанию 8088)
+--no-auto-update           не включать ночное автообновление
+--locale LOCALE            локаль установщика и системы (по умолчанию en_US.UTF-8)
+--keyboard LAYOUT          раскладка (по умолчанию us)
+--timezone TZ              часовой пояс (по умолчанию geoip — установщик определит по сети; мастер настройки может сменить)
 --no-wheels                не класть Python-колёса (тогда первая загрузка скачает их из PyPI)
---repo-url URL             откуда нода будет получать обновления
 ```
 
-Через make параметры передаются так:
+Полностью автоматический режим (вопросов нет, **стирается самый большой диск**):
+
+```text
+--unattended               автоматическая установка
+--username NAME            администратор (логин в панель), обязателен с --unattended
+--password-hash HASH       хеш crypt(3), например от: openssl passwd -6
+--hostname NAME            имя сервера (по умолчанию virtuality)
+```
+
+`./image/build-iso.sh --help` печатает тот же список. Через `make` параметры передаются так:
 
 ```bash
 make iso ISO_ARGS="--web-port 8089 --no-auto-update --timezone Europe/Moscow"
 ```
 
+### Что кладётся в образ
+
+- **Исходники**: `git clone` репозитория на указанный `--ref`; у клона `origin` переключается на `--repo-url`, чтобы нода обновлялась оттуда.
+- **Колёса**: `pip download` для Python целевого выпуска (3.14 для Ubuntu 26.04, 3.12 для 24.04) и архитектуры, только бинарные `manylinux`-колёса из `web/requirements.txt`. Сам `pip` тоже кладётся: в Ubuntu Server нет `python3-venv`, и установщик панели поднимает pip из этого колеса в virtualenv, созданный `--without-pip`. Благодаря этому панель ставится до появления сети.
+- **`image.env`**: `VIRTUALITY_IMAGE_VERSION`, `VIRTUALITY_IMAGE_BUILT`, `VIRTUALITY_WEB_PORT`, `VIRTUALITY_AUTO_UPDATE` и, в автоматическом режиме, `VIRTUALITY_USER`. Установщик копирует файл в `/etc/virtuality/image.env`, его читает первая загрузка.
+
 ### Полностью автоматическая установка
 
-Для массовой раскатки можно собрать образ, который не задаёт вопросов:
+Для массовой раскатки:
 
 ```bash
 make iso ISO_ARGS="--unattended --username admin --password-hash '$(openssl passwd -6)' --hostname node01"
 ```
 
-> ⚠️ Такой образ загружается в установку сам (через 10 секунд в меню) и **без подтверждения стирает самый большой диск** машины. Файл получает суффикс `-unattended`. Не оставляйте такую флешку в серверах.
+> ⚠️ Такой образ сам уходит в установку через 10 секунд в меню и **без подтверждения стирает самый большой диск** машины. Файл получает суффикс `-unattended`, пункты меню — пометку «автоматически, диск будет стёрт». Не оставляйте такую флешку в серверах.
+
+---
+
+## Что спрашивает установщик
+
+Меню загрузки: **Установить Virtuality 0.11.0** (выбирается сам через 10 секунд), тот же пункт с новым ядром HWE, загрузка с другого диска, настройки UEFI, проверка памяти.
+
+Сценарий `image/autoinstall.yaml` оставляет интерактивными только три экрана установщика Ubuntu:
+
+1. **Сеть** — обычно достаточно подтвердить адрес по DHCP.
+2. **Диск** — какой диск использовать. Разметка: LVM на весь диск.
+3. **Пользователь** — имя сервера, имя пользователя и пароль. Этот пользователь становится администратором панели (и входит по SSH).
+
+Язык, раскладка, часовой пояс (по умолчанию определяется по сети), SSH-сервер с входом по паролю и всё остальное заданы заранее. В конце установщик копирует исходники в `/opt/virtuality/source`, `image.env` в `/etc/virtuality/` и включает `virtuality-firstboot.service`. Затем — перезагрузка.
+
+---
+
+## Первая загрузка
+
+`scripts/virtuality_firstboot.sh` запускается службой `virtuality-firstboot.service` один раз. Порядок шагов сделан так, чтобы панель появилась первой и показывала прогресс всего остального:
+
+| Шаг | Что происходит | Что видно |
+|---|---|---|
+| `panel` | `scripts/install_web_panel.sh` с `VIRTUALITY_PANEL_ONLY=1`: панель ставится офлайн из колёс и запускается. | Через минуту после загрузки панель отвечает на `http://адрес:8088`; на экране сервера — подсказка `Virtuality настраивается`. |
+| `network` | Ожидание маршрута по умолчанию и DNS. | Если через 20 секунд сети нет, мастер пишет «Нет доступа в интернет. Подключите кабель или настройте сеть — установка продолжится сама». |
+| `virtualization` | `install_virtuality_node.sh`: пакеты KVM/QEMU/libvirt, пулы, firewall. Самый долгий шаг, 5–15 минут. | Мастер показывает, какой пакет скачивается, распаковывается или настраивается. |
+| `tools` | `scripts/install_healthcheck_command.sh`: команда `vhealth`. | |
+| `finish` | `virtuality-ctl reconfigure`: юниты, firewall, перезапуск панели; на экран сервера выводится адрес панели и логин. | Мастер переходит к шагу «Сервер». |
+
+Прогресс пишется в `/var/lib/virtuality/config/setup.json` (`stage`, `message`, список шагов со статусами), мастер опрашивает его через `/api/setup/state`. Каждый шаг идемпотентен и отмечается флагом в `/var/lib/virtuality/.firstboot-steps/`; если что-то упало, systemd перезапускает скрипт через 60 секунд, и он продолжает с первого незавершённого шага — мастер в это время показывает ошибку и хвост журнала. По завершении создаётся `/var/lib/virtuality/.firstboot-done`, и служба больше не запускается.
+
+Если образ собран с `--no-wheels`, офлайн-установка панели не удастся; скрипт дождётся сети и поставит зависимости из PyPI.
+
+Смотреть ход установки с сервера:
+
+```bash
+sudo journalctl -fu virtuality-firstboot
+cat /var/log/virtuality/firstboot.log
+```
+
+Логин в панель — пользователь из установщика, пароль — его пароль. Дальше вас ведёт мастер настройки (см. README).
+
+---
+
+## Тема загрузочного меню
+
+`image/grub/theme.txt` — тема GRUB (gfxmenu), `background.png` — фон 1024×768, `select_*.png` — подсветка выбранного пункта. `build-iso.sh` дописывает в `grub.cfg` подключение темы (`gfxterm`, шрифт `unicode.pf2`, `gfxmode=1024x768`); если модуль или шрифт недоступны, GRUB показывает обычное текстовое меню. Пункты меню переводятся на русский, таймаут — 10 секунд. Контрольная сумма изменённого `grub.cfg` обновляется в `md5sum.txt`, чтобы проверка целостности ISO проходила.
+
+Фон рендерится из `image/grub/background.html` (тот же стиль, что у страницы входа панели), как описано в `image/grub/README.md`.
+
+---
+
+## Проверка образа
+
+Сверьте контрольную сумму скачанного или собранного образа:
+
+```bash
+sha256sum -c virtuality-0.11.0-ubuntu-26.04-amd64.iso.sha256
+```
+
+Убедиться, что образ загрузочный и содержит нужные файлы (то же делает CI):
+
+```bash
+xorriso -indev virtuality-0.11.0-ubuntu-26.04-amd64.iso -report_el_torito plain 2>/dev/null | grep UEFI
+xorriso -osirrox on -indev virtuality-0.11.0-ubuntu-26.04-amd64.iso -extract /autoinstall.yaml autoinstall.yaml
+```
 
 ---
 
 ## Запись на флешку
 
-Linux / macOS:
+Нужна флешка от 4 ГБ. Все данные на ней будут стёрты.
 
-```bash
-sudo dd if=dist/virtuality-0.10.0-ubuntu-26.04-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync
-```
+- **Windows**: [Rufus](https://rufus.ie) (режим записи DD) или [balenaEtcher](https://etcher.balena.io).
+- **macOS**: balenaEtcher.
+- **Linux**: balenaEtcher или `dd`, где `/dev/sdX` — устройство флешки (проверьте через `lsblk`):
 
-Windows: Rufus (режим DD) или balenaEtcher.
+  ```bash
+  sudo dd if=dist/virtuality-0.11.0-ubuntu-26.04-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync
+  ```
 
-Проверка целостности:
-
-```bash
-cd dist && sha256sum -c virtuality-0.10.0-ubuntu-26.04-amd64.iso.sha256
-```
-
----
-
-## Сборка в GitHub Actions
-
-Workflow `.github/workflows/image.yml` собирает ISO:
-
-- автоматически при пуше тега `v*` (amd64 и arm64);
-- вручную: Actions → **Build ISO image** → Run workflow.
-
-Образы Ubuntu Server больше лимита GitHub Releases (2 GB на файл), поэтому ISO публикуются как **artifacts** workflow и хранятся 30 дней.
+Загрузитесь с флешки (меню загрузки — обычно F8, F11, F12 или Esc при включении), выберите **Установить Virtuality**.
 
 ---
 
 ## Ограничения
 
-- База образа — Ubuntu Server 26.04 LTS (или 24.04 LTS через `--ubuntu 24.04`).
-- Для первой загрузки нужен интернет: пакеты KVM/libvirt/Cockpit ставятся из репозиториев Ubuntu. Python-зависимости панели уже лежат в образе.
-- ARM64-образ рассчитан на серверы с UEFI. Raspberry Pi и Orange Pi 5 грузятся иначе — для них используйте их штатный образ Ubuntu Server и `install.sh`.
+- База — Ubuntu Server 26.04 LTS или 24.04 LTS (`--ubuntu 24.04`).
+- Для первой загрузки нужен интернет: пакеты KVM/libvirt ставятся из репозиториев Ubuntu. Панель и её Python-зависимости уже в образе.
+- ARM64-образ рассчитан на серверы с UEFI. Raspberry Pi и Orange Pi 5 загружаются иначе — для них используйте штатный Ubuntu Server для платы и `install.sh`.

docs/REQUIREMENTS.md

@@ -1,95 +1,77 @@
-# Системные требования Virtuality
+# Требования
 
-Virtuality — это серверная система управления виртуализацией на базе KVM/QEMU/libvirt/Cockpit и собственной web-панели.
+## Коротко
 
-## Минимальные требования
+Подойдёт почти любой компьютер или мини-ПК не старше 10 лет с проводной сетью и включённой в BIOS/UEFI виртуализацией. Для одной-двух небольших машин достаточно 4 ГБ памяти; для Windows и нескольких машин сразу — 16 ГБ и SSD.
 
-Подходят только для тестового стенда и одной-двух лёгких VM.
+## Операционная система
 
-```text
-CPU: 2 ядра с аппаратной виртуализацией Intel VT-x / AMD-V
-RAM: 4 GB
-Диск /: минимум 8 GB свободно
-Диск под /var/lib/virtuality: минимум 20 GB свободно
-OS: Ubuntu Server 24.04 LTS / Debian-like с apt
-Network: один проводной интерфейс
-```
+Virtuality работает на:
 
-## Рекомендуемые требования
+- **Ubuntu Server 26.04 LTS** — основа установочного ISO, рекомендуется;
+- **Ubuntu Server 24.04 LTS**;
+- **Debian 13**.
 
-Для нормальной работы нескольких VM.
+Другие системы на базе Debian/Ubuntu с `apt` скорее всего заработают, но не проверяются. Нужен systemd и netplan (для режима «домашняя сеть»). Установка с ISO делает всё сама; на готовую систему Virtuality ставится скриптом `install.sh` — ставьте её на чистый сервер, а не на рабочий компьютер.
 
-```text
-CPU: 4+ ядра с Intel VT-x / AMD-V
-RAM: 16+ GB
-Диск: 100+ GB SSD/NVMe под /var/lib/virtuality
-Network: проводной интерфейс 1 Gbit/s+
-OS: Ubuntu Server 24.04 LTS
-```
+## Процессор и память
 
-## Проверки установщика
+| | Минимум | Рекомендуется |
+|---|---|---|
+| Процессор | 2 ядра x86_64 с Intel VT-x / AMD-V | 4+ ядер |
+| Память | 4 ГБ | 16 ГБ и больше |
+| Системный диск | 8 ГБ свободно на `/` | SSD |
+| Диск под машины | 20 ГБ свободно в `/var/lib` | 100+ ГБ SSD/NVMe, лучше отдельный диск |
+| Сеть | один проводной интерфейс | 1 Гбит/с |
 
-`bootstrap.sh` и `install_virtuality_node.sh` проверяют:
+Как считать память: сервер и панель занимают около 1 ГБ, остальное делят машины. Ubuntu Server внутри машины — от 1 ГБ, Windows 11 — от 4 ГБ (лучше 8). Диск машины занимает место постепенно, по мере заполнения, но резервные копии и снимки требуют запаса: планируйте хотя бы вдвое больше, чем суммарный размер дисков машин.
 
-- наличие root-прав;
-- наличие `apt`;
-- свободное место на `/`;
-- свободное место для `/var/lib`;
-- объём RAM;
-- количество CPU cores;
-- наличие флага аппаратной виртуализации `vmx` или `svm`.
+**Виртуализация должна быть включена в BIOS/UEFI** (Intel VT-x / Virtualization Technology, AMD-V / SVM Mode). Без неё машины будут работать через медленную программную эмуляцию; панель предупредит об этом в разделе «Сервер», а `sudo vhealth` покажет ошибку `/dev/kvm missing`.
 
-## Значения по умолчанию
+Внутри другой виртуальной машины или на VPS Virtuality работает, только если включена вложенная виртуализация (nested virtualization).
+
+## ARM64
+
+Платы и серверы на ARM64 (Raspberry Pi 4/5, Orange Pi 5, серверы с UEFI) поддерживаются: панель определяет профиль, ставит `qemu-system-arm` и прошивку UEFI для ARM. Гости на таких серверах — **только ARM64** (в каталоге готовых систем есть образы aarch64 для Ubuntu, Debian и Alpine); образы x86_64 на них не запускаются. Установка Windows на ARM64 не проверялась.
+
+Для Raspberry Pi и Orange Pi желательно 8 ГБ памяти и загрузка с SSD/NVMe. Установочный ISO для них не подходит (они грузятся иначе) — используйте штатный Ubuntu Server для платы и `install.sh`. ARM64-ISO предназначен для серверов с UEFI.
+
+## Сеть
+
+- Проводное подключение к роутеру. По Wi-Fi сервер работать может, но режим «домашняя сеть» (мост) недоступен — только NAT.
+- Доступ в интернет при установке: первая загрузка после ISO и `install.sh` скачивают пакеты из репозиториев Ubuntu/Debian (сотни мегабайт). Панель после установки в интернет не ходит, кроме проверки обновлений и скачивания образов по вашей команде.
+- Порты на сервере: `8088` (панель по HTTP), `8443` (панель по HTTPS), `22` (SSH). Открывать их на роутере наружу не обязательно и без HTTPS не рекомендуется.
+- Для сети NAT машинам выделяется подсеть `192.168.100.0/24` — она не должна совпадать с вашей домашней сетью. Если роутер раздаёт именно `192.168.100.x`, выбирайте режим «домашняя сеть» или смените подсеть роутера.
+- Если хотите, чтобы сервисы машин были доступны из интернета, потребуется проброс портов на роутере на адрес сервера (и «белый» адрес от провайдера).
+
+## Что проверяет установщик
+
+`install.sh` и `install_virtuality_node.sh` перед установкой проверяют права root, наличие `apt`, свободное место на `/` и в `/var/lib`, память, количество ядер и флаг виртуализации `vmx`/`svm`. Пороги можно изменить переменными окружения:
 
 ```text
 VIRTUALITY_MIN_ROOT_FREE_MB=8192
 VIRTUALITY_MIN_VAR_FREE_MB=20480
 VIRTUALITY_MIN_RAM_MB=4096
 VIRTUALITY_MIN_CPU_CORES=2
+VIRTUALITY_SKIP_REQUIREMENTS=1    # отключить проверки совсем — только для тестов
 ```
 
-## Переопределение требований
-
-Для тестового стенда можно временно уменьшить требования:
+Например, для тестового стенда с маленьким диском:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/viktor138irk/virtuality/main/bootstrap.sh | sudo VIRTUALITY_MIN_VAR_FREE_MB=8192 bash
+curl -fsSL https://raw.githubusercontent.com/viktor138irk/virtuality/main/install.sh | VIRTUALITY_MIN_VAR_FREE_MB=8192 bash
 ```
 
-Полностью отключить preflight-проверки можно так:
+Установка с ISO эти пороги не применяет: диск и память проверяются мастером настройки, который покажет предупреждение, но не остановит установку.
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/viktor138irk/virtuality/main/bootstrap.sh | sudo VIRTUALITY_SKIP_REQUIREMENTS=1 bash
-```
-
-Использовать отключение проверок стоит только для тестов. Для реального сервера это плохая идея: VM быстро съедают диск.
-
-## Как быстро проверить место
+Освободить место перед установкой на существующей системе:
 
 ```bash
 df -h
-df -i
-du -xh / --max-depth=1 2>/dev/null | sort -h
-```
-
-## Очистка перед установкой
-
-```bash
-sudo apt clean
-sudo apt autoclean
-sudo apt autoremove -y
-sudo rm -rf /var/lib/apt/lists/*
-sudo rm -rf /tmp/* /var/tmp/*
+sudo apt clean && sudo apt autoremove -y
 sudo journalctl --vacuum-time=3d
 ```
 
-## Где Virtuality хранит данные
+## Браузер
 
-```text
-/opt/virtuality                 # системные конфиги и установленная web-панель
-/home/<user>/virtuality          # GitHub-репозиторий проекта
-/var/lib/virtuality/iso          # ISO-образы
-/var/lib/virtuality/images       # qcow2-диски VM
-/var/lib/virtuality/backups      # будущие backup VM
-/var/log/virtuality              # логи установки и диагностики
-```
+Панель работает в актуальных Chrome, Firefox, Safari и Edge, в том числе на телефоне. Экран машины (noVNC) требует поддержки WebSocket — она есть во всех перечисленных. При включённом HTTPS сертификат выпускается самим сервером, поэтому браузер один раз спросит, доверять ли ему.

docs/ROADMAP.md

@@ -1,115 +1,46 @@
-# Roadmap Virtuality
+# Планы
 
-Документ фиксирует направление разработки, чтобы проект не превратился в хаотичный комбайн.
+Virtuality — панель для одного домашнего сервера. Этот документ честно фиксирует, что уже есть в версии 0.11 и что планируется дальше. Порядок в списке планов — примерный приоритет, сроков нет. Подробный журнал изменений по версиям — в `updates/versions.json` и в разделе «Обновления» панели.
 
-## v0.1 — Фундамент ноды
+## Сделано в 0.11
 
-Цель: получить рабочую базу для запуска виртуализации.
+**Установка и настройка**
 
-Задачи:
+- Установочный ISO на базе Ubuntu Server 26.04 LTS (amd64, arm64), сборка `make iso` и в GitHub Actions, полностью автоматический режим.
+- Первая загрузка: панель ставится первой и показывает ход установки в браузере, при ошибке продолжает сама.
+- Мастер настройки: часовой пояс, пароль, HTTPS, сеть машин (NAT или домашняя сеть с автооткатом), отдельный диск под машины, обновления.
+- Страница «Настройки», команда `virtuality-ctl`, установка одной командой на Ubuntu 24.04 / 26.04 и Debian 13.
 
-- базовый установщик `install_virtuality_node.sh`;
-- установка KVM/QEMU/libvirt;
-- установка Cockpit и Cockpit Machines;
-- создание директорий хранения;
-- создание libvirt storage pools;
-- базовая настройка firewall;
-- подготовка GitHub-синхронизации;
-- документация проекта.
+**Машины**
 
-## v0.2 — Сеть и диагностика
+- Создание с ISO с выбором типа системы: Linux, Windows 11 / Server 2025 (UEFI + TPM), Windows 10, другая.
+- Машина из готового образа за минуту: каталог (Ubuntu 26.04/24.04, Debian 13, Alpine), скачивание по ссылке, cloud-init с пользователем, паролем и SSH-ключом, гостевой агент.
+- Снимки (до 8 на машину), резервные копии с восстановлением, клонирование, увеличение диска, пауза и спящий режим, заметки, живая нагрузка.
+- Экран машины в браузере только через панель (VNC закрыт снаружи).
 
-Цель: безопасно подготовить сетевую основу.
+**Сеть и сервер**
 
-Задачи:
+- Сеть NAT с постоянными адресами, пробросы портов с проверкой и восстановлением после перезагрузки, домашняя сеть через мост `br0`.
+- HTTPS для панели, стабильный канал обновлений и ранний доступ, откат, ежедневное обслуживание, отчёт для поддержки, архив настроек.
+- Убрано: Cockpit, консольный dashboard, эмуляция ARM64 на x86, загрузка по PXE, старые вспомогательные скрипты.
 
-- диагностический скрипт ноды;
-- определение активного сетевого интерфейса;
-- безопасная настройка bridge `br0`;
-- резервная копия сетевых конфигов перед изменением;
-- откат сетевой конфигурации;
-- улучшение логов установщика.
+## Планируется
 
-## v0.3 — Прототип панели
+- **Резервные копии по расписанию из панели** — сейчас копия по расписанию делается только командой в терминале; нужен график и хранение N последних копий.
+- **Копии на внешний диск или сетевую папку** — сейчас копии лежат только в `/var/lib/virtuality/backups`.
+- **Контейнеры LXC** — лёгкие Linux-контейнеры рядом с машинами, как в Proxmox.
+- **Проброс устройств (PCI/USB passthrough)** — видеокарты, USB-ключи, диски целиком в машину.
+- **Второй сервер (кластер из двух нод)** — общий список машин, перенос машины между серверами, копии на соседний сервер.
+- **Пользователи и роли** — сейчас в панель входит один администратор; нужны дополнительные пользователи с ограниченными правами.
+- **Уведомления** — о завершении задач, ошибках, нехватке места и доступных обновлениях (почта, Telegram).
+- **Шаблоны машин** — сохранить настроенную машину как шаблон и создавать из него новые.
+- **Дополнительные диски и сети у машины** — второй диск, вторая сетевая карта, изменение сети существующей машины.
+- **Сертификат Let's Encrypt** — вместо самоподписанного, для доступа к панели по доменному имени.
+- **История нагрузки** — графики процессора, памяти и диска за день и неделю по серверу и машинам.
+- **Проверка обновлений образов каталога** — предлагать обновить скачанный облачный образ, когда вышел новый.
 
-Цель: начать собственную панель управления.
+## Не планируется
 
-Задачи:
-
-- лёгкая веб-панель;
-- авторизация;
-- список виртуальных машин;
-- статус VM;
-- старт/стоп/перезагрузка VM через libvirt;
-- отображение storage pools;
-- базовый журнал событий.
-
-## v0.4 — Создание VM
-
-Цель: добавить мастер создания виртуальных машин.
-
-Задачи:
-
-- менеджер ISO;
-- форма создания VM;
-- выбор CPU/RAM/disk;
-- выбор ISO;
-- выбор сети;
-- создание qcow2-диска;
-- запуск установки ОС;
-- базовая консоль.
-
-## v0.5 — Обновления и бэкапы
-
-Цель: сделать платформу обслуживаемой.
-
-Задачи:
-
-- автообновлятор;
-- резервная копия конфигов перед обновлением;
-- история обновлений;
-- ручной backup VM;
-- список бэкапов;
-- восстановление из backup.
-
-## v0.6 — Пользователи и роли
-
-Цель: подготовить систему к реальному использованию несколькими пользователями.
-
-Задачи:
-
-- роли: admin, operator, viewer;
-- ограничения действий по ролям;
-- журнал действий пользователей;
-- базовые настройки безопасности.
-
-## v0.7 — Мониторинг
-
-Цель: видеть состояние ноды без терминального шаманства.
-
-Задачи:
-
-- CPU/RAM/disk usage;
-- статус libvirt;
-- статус Cockpit;
-- количество VM;
-- состояние storage pools;
-- алерты;
-- Telegram/email-уведомления в будущем.
-
-## v1.0 — Первый стабильный релиз
-
-Цель: рабочая одиночная нода Virtuality.
-
-Минимальный состав:
-
-- установка одной командой;
-- управление VM;
-- создание VM;
-- сеть bridge;
-- ISO manager;
-- backup/restore;
-- web dashboard;
-- базовая безопасность;
-- документация;
-- обновлятор.
+- Многосерверные кластеры с общим хранилищем, Ceph, живая миграция — это уровень Proxmox для дата-центров, не для дома.
+- Поддержка других гипервизоров, кроме KVM/QEMU/libvirt.
+- Гости x86_64 на ARM64-серверах через эмуляцию — слишком медленно, чтобы этим пользоваться.