#Building VM Images
This guide is for people who want to build modules declaratively — a module is a collection of one or more virtual machines that get built, snapshotted, and cloned as a single group. You write a YAML configuration that describes the VMs in the module, their base images, provisioning steps, and any networking, ISOs, or files they need during the build. The system boots the VMs, runs each VM's steps, captures their disks, and saves them as a reusable template module.
You don't need to know how it works internally — the rest of this guide just tells you what to put in the configuration.
- Mental Model — If you've ever built an image for a class, you know how tedious the process is. By the time you need to rebuild it for next semester, half the context is gone. We hit this over and over, and decided there had to be a better way. That's why we require every image we build to be scripted and repeatable. Every module is an automated build, and every build must be reproducible from its YAML alone.
- Concepts — Each section of the build YAML, explained one at a time. Pick whichever piece you're trying to understand.
- Recipes — Full worked examples for the situations you're most likely to hit.
- Best Practices — Reboot any time a step changes something that needs a clean process tree:
- Troubleshooting — Network resources couldn't be created. Check that:
- Reference
- Under the Hood — You don't need any of this to write a build. It's here so the names you'll run into in upstream documentation, log output, and community forums make sense.