virtuality/docs/IMAGE.md

Установочный образ Virtuality

Virtuality можно поставить двумя способами:

1. Скрипт на готовый сервер — curl ... install.sh | bash (см. README).
2. Установочный ISO — загрузочный образ «с нуля», как у Proxmox: записываете на флешку, загружаетесь, отвечаете на 3 экрана, после перезагрузки получаете готовую ноду.

Этот документ про второй способ.

---

Что внутри образа

Образ собирается из официального Ubuntu Server 24.04 LTS live-server ISO (amd64 или arm64) и дополняется:

/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»

Загрузочные записи 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. Готово:

Web-панель: http://SERVER_IP:8088   (логин — пользователь, созданный в установщике)
Cockpit:    https://SERVER_IP:9090

Адрес панели также показывается на экране входа консоли. Ход первой настройки:

sudo journalctl -fu virtuality-firstboot
cat /var/log/virtuality/firstboot.log

---

Сборка ISO

Нужна Linux-машина (root не нужен), ~10 GB свободного места и пакеты:

sudo apt install -y xorriso git curl python3-pip

Сборка:

git clone https://github.com/viktor138irk/virtuality.git
cd virtuality
make iso                 # amd64
make iso ARCH=arm64      # ARM64-серверы с UEFI

Скрипт сам скачает последний Ubuntu 24.04.x live-server ISO, проверит SHA256 и положит результат в dist/:

dist/virtuality-0.10.0-ubuntu-24.04-amd64.iso
dist/virtuality-0.10.0-ubuntu-24.04-amd64.iso.sha256

Скачанный ISO Ubuntu кешируется в .cache/iso. Уже скачанный образ можно передать явно:

./image/build-iso.sh --ubuntu-iso ~/Downloads/ubuntu-24.04.5-live-server-amd64.iso

Параметры

--arch amd64|arm64         архитектура
--ref GIT_REF              какую версию Virtuality положить в образ (по умолчанию HEAD)
--web-port PORT            порт web-панели (по умолчанию 8088)
--no-auto-update           не включать ночное автообновление с GitHub
--locale / --keyboard / --timezone
--no-wheels                не класть Python-колёса (тогда первая загрузка скачает их из PyPI)
--repo-url URL             откуда нода будет получать обновления

Через make параметры передаются так:

make iso ISO_ARGS="--web-port 8089 --no-auto-update --timezone Europe/Moscow"

Полностью автоматическая установка

Для массовой раскатки можно собрать образ, который не задаёт вопросов:

make iso ISO_ARGS="--unattended --username admin --password-hash '$(openssl passwd -6)' --hostname node01"

⚠️ Такой образ загружается в установку сам (через 10 секунд в меню) и без подтверждения стирает самый большой диск машины. Файл получает суффикс -unattended. Не оставляйте такую флешку в серверах.

---

Запись на флешку

Linux / macOS:

sudo dd if=dist/virtuality-0.10.0-ubuntu-24.04-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync

Windows: Rufus (режим DD) или balenaEtcher.

Проверка целостности:

cd dist && sha256sum -c virtuality-0.10.0-ubuntu-24.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 дней.

---

Ограничения

• Целевая ОС образа — Ubuntu Server 24.04 LTS.
• Для первой загрузки нужен интернет: пакеты KVM/libvirt/Cockpit ставятся из репозиториев Ubuntu. Python-зависимости панели уже лежат в образе.
• ARM64-образ рассчитан на серверы с UEFI. Raspberry Pi и Orange Pi 5 грузятся иначе — для них используйте их штатный образ Ubuntu Server и install.sh.