Development guide
Updated
This section documents how Virtainer Free is developed. It is written for the person who needs to change the code, build a release, or reproduce a host image, and it states what the tooling enforces rather than what somebody remembers.
Everything here is verifiable in the virtainer-lite source tree. Where a claim comes
from a specific file, the file is named so you can read it instead of trusting this page.
When the three disagree, the code wins and the document is the bug.
The shape of it
Section titled “The shape of it”Virtainer Free is one Rust daemon per host. It owns that host’s virtual machines,
storage, networking and first-boot setup, and serves them from a web console that is
compiled into the same binary. There is no external control plane and no separate
frontend server: the host is the source of truth (ADR-0001,
docs/adr/0001-standalone-single-host.md).
Two kinds of workload run side by side on it. A VM is a cloud image with its own kernel, qcow2 disks and a serial console. An AppVM is an OCI container image booted as a single-container microVM, so it gets hardware isolation while keeping the “point it at an image” ergonomics.
Where to start
Section titled “Where to start”| You want to | Read |
|---|---|
| Get the code building and running locally | Building from source |
| Know which tests exist and what each one proves | Testing |
| Understand the repo and where a change belongs | Repository layout |
| Build or change the whole-machine host image | The bootc host image |
| Cut a release and get it accepted on real hardware | Releasing |
| Match the conventions the gates enforce | Conventions |