docs: add virt-manager realm setup guide (#538)

slashburygin · sourcery-ai[bot] · web-flow · commit 143bdcd9e74a · 2026-08-03T22:45:37.000+03:00
* docs: add virt-manager realm setup guide

* Update docs/realms/realm-virt-manager.ru.md

Co-authored-by: sourcery-ai[bot] &lt;58596630+sourcery-ai[bot]@users.noreply.github.com&gt;

* Update docs/realms/realm-virt-manager.md

Co-authored-by: sourcery-ai[bot] &lt;58596630+sourcery-ai[bot]@users.noreply.github.com&gt;

---------

Co-authored-by: sourcery-ai[bot] &lt;58596630+sourcery-ai[bot]@users.noreply.github.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -139,3 +139,4 @@ docs/source/*.png
 pgdata/
 
 .tasks
+graphify-out
diff --git a/docs/realms/realm-virt-manager.md b/docs/realms/realm-virt-manager.md
@@ -0,0 +1,112 @@
+# Running Exordos Realm with virt-manager
+
+> **Console-access note:** The production realm-node artifact is intended to
+> be configured by a parent realm and does **not** provide console access. To
+> operate a standalone developer stand, use image exordos-realm-dev.raw.zst.
+
+## Create and run the VM
+
+These commands download the dev image, expand it, and create an
+importable disk. Run them on an Ubuntu/Debian KVM host:
+
+```bash
+sudo apt update
+sudo apt install -y qemu-kvm libvirt-daemon-system libvirt-clients virt-manager zstd
+sudo usermod -aG libvirt,kvm "$USER"
+# Log out and back in once for the new group membership to take effect.
+
+cd /var/lib/libvirt/images/
+sudo wget -O exordos-realm-dev.raw.zst \
+  https://repo.exordos.com/exordos-elements/exordos-realm/latest/images/exordos-realm-dev.raw.zst
+sudo zstd --decompress --keep exordos-realm-dev.raw.zst
+sudo chown libvirt-qemu:kvm exordos-realm-dev.raw
+sudo qemu-img info exordos-realm-dev.raw
+```
+
+The host must expose nested KVM to the guest because the realm node runs a
+nested core VM. Check the relevant value before creating the VM:
+
+```bash
+# Intel hosts
+cat /sys/module/kvm_intel/parameters/nested
+# AMD hosts
+cat /sys/module/kvm_amd/parameters/nested
+```
+
+It must print `Y` (or `1`). Enable nested virtualization on the host before
+continuing if it does not.
+
+Start virt-manager and select the system libvirt connection:
+
+```bash
+virt-manager --connect qemu:///system
+```
+
+In the GUI, select **File → New Virtual Machine**, then configure:
+
+1. Select **Import existing disk image**.
+2. Select `/var/lib/libvirt/images/exordos-realm-dev.raw`; choose a recent Ubuntu OS
+   type (for example, Ubuntu 24.04) if virt-manager asks.
+3. Allocate at least **4 vCPUs** and **8192 MiB RAM**; use more resources if the nested core workload requires it.
+4. Keep the default NAT network or choose a bridged network appropriate for
+   the host.
+5. Tick **Customize configuration before install**. In **CPUs**, select
+   **Copy host CPU configuration** / host-passthrough so KVM virtualization
+   extensions are visible to the guest. Ensure the disk uses the `raw` format
+   and virtio bus, then click **Begin Installation**.
+
+The following fully command-line import is equivalent and registers the VM so
+it can be opened and managed with virt-manager:
+
+```bash
+virt-install --connect qemu:///system \
+  --name exordos-realm \
+  --memory 8192 \
+  --vcpus 4 \
+  --cpu host-passthrough \
+  --disk path=/var/lib/libvirt/images/exordos-realm-dev.raw,format=raw,bus=virtio \
+  --network network=default,model=virtio \
+  --os-variant ubuntu24.04 \
+  --graphics spice \
+  --video virtio \
+  --import --noautoconsole
+
+# Open the VM's graphical console in virt-manager.
+virt-manager --connect qemu:///system --show-domain-console exordos-realm
+```
+
+## Test the VM
+
+After starting it, confirm that libvirt reports it as running and that KVM is
+available inside the realm node:
+
+```bash
+virsh --connect qemu:///system list --all
+virsh --connect qemu:///system dominfo exordos-realm
+
+# Run this in the guest console (a DEV_ACCESS image is required to log in).
+kvm-ok
+```
+
+`virsh` should show `exordos-realm` as `running`; `kvm-ok` should report that
+KVM acceleration can be used. For a DEV_ACCESS image, log in as
+`ubuntu:ubuntu`.
+The production image will wait for `/etc/exordos/realm_spec.json` from its
+parent realm rather than offering standalone console access.
+
+## Developer stand
+
+Simulate the managed flow by writing `/etc/exordos/realm_spec.json`
+yourself (see the contract in exordos_ecosystem `docs/realm-manager.md`, or you can copy example spec
+by `cp /etc/exordos/realm_spec.json.example /etc/exordos/realm_spec.json`) —
+the first-boot unit picks it up.
+
+Key names deliberately match the `spec.json` keys consumed by
+`exordos_core/cmd/bootstrap.py` / `exordos_core/bootstrap/defaults.py`
+(`realm_uuid`, `realm_secret`, `realm_tokens`, `ecosystem_endpoint`,
+`admin_password`, `disable_telemetry`), so the image's first-boot script can
+merge this file into its baked spec template with minimal mapping.
+
+Next you can view the bootstrap service logs with `sudo journalctl -u exordos-realm-bootstrap`.
+
+And after few seconds you can see work stand by `exordos e e l`.
diff --git a/docs/realms/realm-virt-manager.ru.md b/docs/realms/realm-virt-manager.ru.md
@@ -0,0 +1,117 @@
+# Запуск Realm Exordos с virt-manager
+
+> **Примечание о консольном доступе:** Артефакт production realm-node
+> предназначен для настройки родительским realm и **не** предоставляет
+> консольного доступа. Для работы автономного стенда разработчика
+> используйте образ exordos-realm-dev.raw.zst.
+
+## Создание и запуск ВМ
+
+Эти команды загружают dev-образ, распаковывают его и создают диск для
+импорта. Выполняйте их на KVM-хосте с Ubuntu/Debian:
+
+```bash
+sudo apt update
+sudo apt install -y qemu-kvm libvirt-daemon-system libvirt-clients virt-manager zstd
+sudo usermod -aG libvirt,kvm "$USER"
+# Выйдите из системы и зайдите снова, чтобы применить новую группу.
+
+cd /var/lib/libvirt/images/
+sudo wget -O exordos-realm-dev.raw.zst \
+  https://repo.exordos.com/exordos-elements/exordos-realm/latest/images/exordos-realm-dev.raw.zst
+sudo zstd --decompress --keep exordos-realm-dev.raw.zst
+sudo chown libvirt-qemu:kvm exordos-realm-dev.raw
+sudo qemu-img info exordos-realm-dev.raw
+```
+
+Хост должен предоставлять вложенный KVM (nested KVM) гостевой системе,
+поскольку realm node запускает вложенную core VM. Проверьте соответствующее
+значение перед созданием ВМ:
+
+```bash
+# Хосты Intel
+cat /sys/module/kvm_intel/parameters/nested
+# Хосты AMD
+cat /sys/module/kvm_amd/parameters/nested
+```
+
+Значение должно быть `Y` (или `1`). Если это не так, включите вложенную
+виртуализацию на хосте прежде чем продолжать.
+
+Запустите virt-manager и выберите системное подключение libvirt:
+
+```bash
+virt-manager --connect qemu:///system
+```
+
+В графическом интерфейсе выберите **Файл → Новая виртуальная машина**, затем
+настройте:
+
+1. Выберите **Импортировать существующий образ диска**.
+2. Укажите `/var/lib/libvirt/images/exordos-realm-dev.raw`; выберите
+   подходящий тип ОС Ubuntu (например, Ubuntu 24.04), если virt-manager
+   запросит.
+3. Выделите не менее **4 vCPU** и **8192 MiB ОЗУ**; увеличьте ресурсы, если
+   этого требует вложенная core-нагрузка.
+4. Оставьте сеть NAT по умолчанию или выберите мостовую сеть, подходящую
+   для хоста.
+5. Отметьте **Настроить конфигурацию перед установкой**. В разделе **CPU**
+   выберите **Копировать конфигурацию CPU хоста** / host-passthrough, чтобы
+   расширения виртуализации KVM были доступны гостю. Убедитесь, что диск
+   использует формат `raw` и шину virtio, затем нажмите **Начать установку**.
+
+Полностью командная строка ниже эквивалентна и регистрирует ВМ так, чтобы её
+можно было открыть и управлять ей через virt-manager:
+
+```bash
+virt-install --connect qemu:///system \
+  --name exordos-realm \
+  --memory 8192 \
+  --vcpus 4 \
+  --cpu host-passthrough \
+  --disk path=/var/lib/libvirt/images/exordos-realm-dev.raw,format=raw,bus=virtio \
+  --network network=default,model=virtio \
+  --os-variant ubuntu24.04 \
+  --graphics spice \
+  --video virtio \
+  --import --noautoconsole
+
+# Откройте графическую консоль ВМ в virt-manager.
+virt-manager --connect qemu:///system --show-domain-console exordos-realm
+```
+
+## Проверка ВМ
+
+После запуска убедитесь, что libvirt сообщает о работе ВМ и что KVM доступен
+внутри realm node:
+
+```bash
+virsh --connect qemu:///system list --all
+virsh --connect qemu:///system dominfo exordos-realm
+
+# Выполните в гостевой консоли (для входа требуется образ DEV_ACCESS).
+kvm-ok
+```
+
+`virsh` должен показать `exordos-realm` в статусе `running`; `kvm-ok` должен
+сообщить, что ускорение KVM может быть использовано. Для образа DEV_ACCESS
+войдите как `ubuntu:ubuntu`.
+Production-образ будет ожидать `/etc/exordos/realm_spec.json` от своего
+родительского realm.
+
+## Стенд разработчика
+
+Смоделируйте создание стенда, написав `/etc/exordos/realm_spec.json`
+самостоятельно (смотрите контракт в exordos_ecosystem `docs/realm-manager.md`, или вы можете скопировать пример спецификации
+с помощью `cp /etc/exordos/realm_spec.json.example /etc/exordos/realm_spec.json`) —
+модуль первой загрузки распознает его.
+
+Имена ключей намеренно совпадают с ключами `spec.json`, используемыми
+`exordos_core/cmd/bootstrap.py` / `exordos_core/bootstrap/defaults.py`
+(`realm_uuid`, `realm_secret`, `realm_tokens`, `ecosystem_endpoint`,
+`admin_password`, `disable_telemetry`), чтобы скрипт первой загрузки образа мог
+объединить этот файл с его готовым шаблоном спецификации с минимальным сопоставлением.
+
+Далее вы можете просмотреть логи службы bootstrap с помощью `sudo journalctl -u exordos-realm-bootstrap`.
+
+И через несколько секунд вы можете увидеть рабочий стенд, выполнив команду `exordos e e l`.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -165,3 +165,4 @@ nav:
   - Secrets:
       - Certificates: secret/certificates.md
       - Passwords: secret/passwords.md
+  - Realms: realms/realm-virt-manager.md

Original file line number	Diff line number	Diff line change
`@@ -139,3 +139,4 @@ docs/source/*.png`
`139`	`139`	`pgdata/`
`140`	`140`
`141`	`141`	`.tasks`
	`142`	`+graphify-out`