Problem
Setting up a forge-based development environment currently requires manually installing Vagrant and a hypervisor provider on the host before running ./forge vms start. DEVELOPMENT.md just links out to forklift's docs/vagrant.md for this, and there's no automated path — unlike forklift, which has a dedicated roles/vagrant role that installs Vagrant/libvirt/vagrant-libvirt, enables libvirtd, and adds the user to the libvirt group.
This came up while working on theforeman/jenkins-jobs#588, which provisions a forge-driven install test on Duffy hosts — those hosts need the same host-level bootstrap before forge/foremanctl can run.
Proposal
Add a new, opt-in forge subcommand (e.g. forge host setup — naming TBD) that provisions the host itself for local development. This is a distinct, one-time step in the environment setup flow — run manually by the user before ./setup-environment / ./forge vms start, not automatically triggered by them. Users who already have their host provisioned (or want to manage it themselves) simply skip it.
- Linux (Fedora / CentOS Stream): Install Vagrant + the libvirt provider stack (mirrors forklift's
roles/vagrant: libvirt-daemon-kvm, vagrant-libvirt, enabling libvirtd/virtnetworkd, COPR repos where needed). Add the invoking user to the libvirt group.
- macOS on Apple Silicon (ARM): Install Vagrant + the
vagrant-qemu provider, since vagrant-libvirt isn't an option there 😂 (yes, I have an M-series MacBook now, don't @ me). Needs its own box/provider selection in the Vagrantfile/vars, since boxes aren't 1:1 portable between libvirt and qemu providers.
- Runs with elevated privileges since it's modifying host packages/services — clearly separate from the existing
forge vms playbooks, which only manage guest VMs and should never implicitly touch the host.
Open questions to resolve during implementation:
- Reimplement the logic in
development/roles/, or depend on/reuse the theforeman.forklift collection's vagrant role directly for the Linux/libvirt path (foremanctl already pulls in the forklift collection transitively for VM lifecycle)? The qemu/macOS path would need new logic regardless, since forklift doesn't support it today.
- How does box selection in the
Vagrantfile need to branch per-provider/per-arch (libvirt boxes vs qemu-compatible boxes)?
- Any macOS-specific package manager assumptions (Homebrew) to bake in for installing Vagrant/vagrant-qemu?
- Where does this fit relative to
./setup-environment — a flag on it, or a fully separate command documented as an earlier optional step in DEVELOPMENT.md?
Why this matters
- Reduces friction for new contributors following
DEVELOPMENT.md.
- Needed for automated CI hosts (e.g. Duffy-provisioned boxes in jenkins-jobs#588) that need a repeatable, non-interactive way to get
forge runnable from a bare host.
- Opens up local development on Apple Silicon MacBooks, which currently isn't documented/supported at all.
Problem
Setting up a
forge-based development environment currently requires manually installing Vagrant and a hypervisor provider on the host before running./forge vms start.DEVELOPMENT.mdjust links out to forklift'sdocs/vagrant.mdfor this, and there's no automated path — unlike forklift, which has a dedicatedroles/vagrantrole that installs Vagrant/libvirt/vagrant-libvirt, enableslibvirtd, and adds the user to thelibvirtgroup.This came up while working on theforeman/jenkins-jobs#588, which provisions a
forge-driven install test on Duffy hosts — those hosts need the same host-level bootstrap beforeforge/foremanctlcan run.Proposal
Add a new, opt-in
forgesubcommand (e.g.forge host setup— naming TBD) that provisions the host itself for local development. This is a distinct, one-time step in the environment setup flow — run manually by the user before./setup-environment/./forge vms start, not automatically triggered by them. Users who already have their host provisioned (or want to manage it themselves) simply skip it.roles/vagrant:libvirt-daemon-kvm,vagrant-libvirt, enablinglibvirtd/virtnetworkd, COPR repos where needed). Add the invoking user to thelibvirtgroup.vagrant-qemuprovider, sincevagrant-libvirtisn't an option there 😂 (yes, I have an M-series MacBook now, don't @ me). Needs its own box/provider selection in theVagrantfile/vars, since boxes aren't 1:1 portable between libvirt and qemu providers.forge vmsplaybooks, which only manage guest VMs and should never implicitly touch the host.Open questions to resolve during implementation:
development/roles/, or depend on/reuse thetheforeman.forkliftcollection'svagrantrole directly for the Linux/libvirt path (foremanctl already pulls in the forklift collection transitively for VM lifecycle)? The qemu/macOS path would need new logic regardless, since forklift doesn't support it today.Vagrantfileneed to branch per-provider/per-arch (libvirt boxes vs qemu-compatible boxes)?./setup-environment— a flag on it, or a fully separate command documented as an earlier optional step inDEVELOPMENT.md?Why this matters
DEVELOPMENT.md.forgerunnable from a bare host.