virtuality/README.md

Virtuality

Virtuality — лёгкая серверная платформа виртуализации в стиле Proxmox на базе KVM, QEMU, libvirt, Cockpit и собственной web-панели.

Цель проекта — собрать понятную, компактную и расширяемую систему для управления виртуальными машинами, ISO-образами, storage pools, сетевыми bridge-интерфейсами, диагностикой и будущими backup/cluster-функциями.

Текущий статус: ранняя стадия разработки. Virtuality уже поднимает KVM/libvirt/Cockpit, создаёт storage pools, имеет web-панель, авторизацию Linux-пользователем, healthcheck и создание VM из интерфейса.

---

Быстрая установка одной командой

Одна команда работает и под root, и под обычным пользователем с sudo:

curl -fsSL https://raw.githubusercontent.com/viktor138irk/virtuality/main/install.sh | bash

Как выбирается пользователь для входа в web-панель:

Если запуск под root      → login: root
Если запуск через sudo    → login: текущий sudo-пользователь
Если задан VIRTUALITY_USER → login: указанный пользователь

Принудительно выбрать пользователя:

curl -fsSL https://raw.githubusercontent.com/viktor138irk/virtuality/main/install.sh | VIRTUALITY_USER=viktor bash

Установка с авторизацией под root:

curl -fsSL https://raw.githubusercontent.com/viktor138irk/virtuality/main/install.sh | VIRTUALITY_USER=root bash

Если пароль выбранного Linux-пользователя не задан:

sudo passwd viktor

или:

passwd root

---

Что уже есть

• универсальная one-command установка через install.sh;
• красивый пошаговый installer с live-status и логами;
• preflight-проверка системных требований;
• установка KVM/QEMU/libvirt;
• установка Cockpit и Cockpit Machines;
• рабочая директория /opt/virtuality/source;
• libvirt storage pools virtuality-images и virtuality-iso;
• firewall-правила для SSH, Cockpit, VNC и web-панели;
• настройка bridge br0 отдельным безопасным скриптом через netplan try;
• healthcheck одной командой vhealth;
• консольный dashboard для физического монитора;
• web-панель Virtuality на FastAPI;
• авторизация web-панели через системного Linux-пользователя;
• список VM;
• управление VM: Start, Shutdown, Reboot, Power off, Autostart on/off, Delete VM with disks;
• создание VM из web-интерфейса;
• страница деталей VM: dominfo, VNC display, диски, сетевые интерфейсы.

---

Системные требования

Минимально для тестового стенда:

CPU: 2 ядра с Intel VT-x / AMD-V
RAM: 4 GB
/: минимум 8 GB свободно
/var/lib: минимум 20 GB свободно
OS: Ubuntu Server 24.04 LTS / Debian-like с apt
Network: один проводной интерфейс

Рекомендуемо для нормальной работы:

CPU: 4+ ядра
RAM: 16+ GB
Storage: 100+ GB SSD/NVMe под /var/lib/virtuality
Network: 1 Gbit/s+
OS: Ubuntu Server 24.04 LTS

Подробнее: docs/REQUIREMENTS.md

---

Порты

Cockpit:       https://SERVER_IP:9090
Virtuality UI: http://SERVER_IP:8088
VNC:           5900-5999/tcp
SSH:           22/tcp

Изменить порт web-панели:

curl -fsSL https://raw.githubusercontent.com/viktor138irk/virtuality/main/install.sh | VIRTUALITY_WEB_PORT=8089 bash

---

Директории

/opt/virtuality/source          # исходники проекта из GitHub
/opt/virtuality/web             # установленная web-панель
/opt/virtuality/venv            # Python virtualenv web-панели
/opt/virtuality/virtuality.env  # базовый env ноды
/var/lib/virtuality/iso         # ISO-образы
/var/lib/virtuality/images      # qcow2-диски VM
/var/lib/virtuality/backups     # backups
/var/log/virtuality             # логи установки и диагностики

---

Диагностика

sudo vhealth

Проверяются CPU virtualization, /dev/kvm, virsh, QEMU, libvirt, Cockpit, web-панель, bridge, netplan, firewall, storage pools, VM, директории, диск и память.

---

Bridge br0

По умолчанию one-command установщик не включает br0 автоматически, чтобы не уронить SSH-сессию.

Сначала нужно посмотреть сетевой интерфейс:

ip -br a
ip route

Затем запустить bridge setup, например для enp2s0:

cd /opt/virtuality/source
sudo bash scripts/setup_bridge_br0.sh enp2s0 static

Ожидаемый результат:

enp2s0  UP
br0     UP  SERVER_IP/24
default via GATEWAY dev br0

---

Web-панель

Переустановка web-панели:

cd /opt/virtuality/source
sudo bash scripts/install_web_panel.sh

Статус:

systemctl status virtuality-web --no-pager

Логи:

journalctl -u virtuality-web -f

Вход:

URL:    http://SERVER_IP:8088
Login:  выбранный Linux-пользователь
Pass:   пароль этого Linux-пользователя

---

Создание тестовой VM

Через web-панель:

Virtuality UI → + Создать VM

Или командой:

cd /opt/virtuality/source
sudo bash scripts/create_test_vm.sh

Alpine ISO:

sudo wget -O /var/lib/virtuality/iso/alpine-standard.iso https://dl-cdn.alpinelinux.org/alpine/v3.20/releases/x86_64/alpine-standard-3.20.3-x86_64.iso
sudo virsh pool-refresh virtuality-iso

---

Повторная установка / обновление

cd /opt/virtuality/source
sudo git pull
sudo bash install_virtuality_node.sh
sudo bash scripts/install_web_panel.sh

---

Полезные команды

sudo vhealth
virsh list --all
virsh pool-list --all
ip -br a
ip route
sudo ufw status
systemctl status libvirtd --no-pager
systemctl status cockpit.socket --no-pager
systemctl status virtuality-web --no-pager

---

Roadmap

• загрузка ISO из web-интерфейса;
• web-console/noVNC;
• управление storage pools;
• backup/snapshot manager;
• сетевой менеджер bridge/VLAN;
• роли и права пользователей;
• журнал событий;
• автообновление;
• кластеризация.

---

Лицензия

Рекомендуемая лицензия: MIT License.