docs: add a QEMU/KVM guide for evaluating TunaOS in a VM (closes #216) - #234
Merged
hanthor-hive-agent[bot] merged 1 commit intoAug 14, 2026
Merged
Conversation
system-requirements.md listed hypervisors and VM specs but there was no guide for actually doing it, so the safest first step for an evaluator had no page. Adds docs/tunaos/evaluating-in-a-vm.md, registered in sidebars.ts under Documentation next to tunaos/introduction, and linked from the Virtualization section of system-requirements.md - the place someone already lands when asking "can I run this in a VM". Every fact is taken from the repo rather than invented: - the ISO table is copied from installation.md (Albacore and Yellowfin, GNOME and GNOME-HWE) - VM specs are the ones already in system-requirements.md (4 GB/25 GB minimum, 8 GB/50 GB recommended), with the disk-usage figures from the same page explaining why 25 GB is tight - next steps point at the existing bootc-usage.md rather than restating layering/upgrade/rollback - the "not sure which variant" path defers to choosing-a-variant.md Covers both virt-manager and raw qemu-system-x86_64, and calls out the two things that actually stop a first attempt: UEFI firmware must be selected (the images will not boot under legacy BIOS) and the OVMF path differs between Fedora- and Debian-family hosts. It also recommends snapshotting straight after first boot, since rollback is the thing most worth trying and a snapshot makes it free. Notes that plain GNOME is the right ISO for a VM - HWE targets newer physical hardware and buys nothing against virtual devices - and that other flavors are reachable via bootc switch rather than an ISO. Verified: npm run build succeeds, the page renders at build/docs/tunaos/evaluating-in-a-vm.html, its references to choosing-a-variant, bootc-usage, installation, system-requirements and download.tunaos.org are all present in the output, and the sidebar entry appears on sibling pages. Docusaurus fails the build on broken links, so a green build is the link check. The one broken-anchor warning (/docs/iso-builder/native/user-guide -> /docs/iso-builder#quick-start) is pre-existing; it appears identically on a pristine build of this commit. Not verified: an actual install run inside a VM. The commands are standard QEMU/virt-manager usage, but someone with a Linux host should confirm the 15-20 minute claim end to end. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #216.
system-requirements.mdlisted hypervisors and VM specs, but there was no guide for actually doing it — so the safest first step for an evaluator had no page.What's here
docs/tunaos/evaluating-in-a-vm.md— the guidesidebars.ts— registered under Documentation, next totunaos/introductiondocs/system-requirements.md— a link from the Virtualization section, which is where someone already lands when asking "can I run this in a VM"Every fact comes from the repo
I deliberately didn't invent any numbers or ISO names:
installation.mdsystem-requirements.mdsystem-requirements.mdbootc-usage.md, not restatedchoosing-a-variant.mdThe parts that actually stop a first attempt
The guide covers both
virt-managerand rawqemu-system-x86_64, and leads with the two things that waste an evening:/usr/share/OVMF/OVMF_CODE.fdon Debian-family,/usr/share/edk2/ovmf/OVMF_CODE.fdon Fedora-family. A copy-pasted command fails on half of hosts otherwise.It also recommends snapshotting immediately after first boot, because rollback is the most interesting thing to try and a snapshot makes trying it free — which is really the argument for evaluating a bootc system in a VM at all.
Two smaller notes: plain GNOME is the right ISO for a VM (HWE targets newer physical hardware and buys nothing against virtual devices), and other flavors are reachable via
bootc switchrather than an ISO.Verification
npm run buildsucceeds; the page renders atbuild/docs/tunaos/evaluating-in-a-vm.htmlchoosing-a-variant,bootc-usage,installation,system-requirementsanddownload.tunaos.orgare all present in the built outputThe one
[WARNING] Docusaurus found broken anchors(/docs/iso-builder/native/user-guide→/docs/iso-builder#quick-start) is pre-existing — I re-ran the build on a stashed working tree and it appears identically there.What I could not verify
An actual install run inside a VM. The commands are standard QEMU/virt-manager usage and the figures are all sourced above, but the issue's "15–20 min for a first-time user" claim deserves a real run by someone on a Linux host before you take it as tested.
While checking for overlap I noticed #214 appears already done —
docs/choosing-a-variant.mdexists and is registered insidebars.ts, added by 59e611c ("docs: add Choosing your TunaOS variant decision guide (#214) (#225)"). Might be worth closing.🤖 Generated with Claude Code