theforeman / theforeman/foremanctl
Add forge subcommand to bootstrap host prerequisites (Vagrant, libvirt / vagrant-qemu)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 27
- Forks
- 47
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 40
Description
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, enablinglibvirtd/virtnetworkd, COPR repos where needed). Add the invoking user to thelibvirtgroup. - macOS on Apple Silicon (ARM): Install Vagrant + the
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. - Runs with elevated privileges since it's modifying host packages/services — clearly separate from the existing
forge vmsplaybooks, 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 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. - How does box selection in the
Vagrantfileneed 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 inDEVELOPMENT.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
forgerunnable from a bare host. - Opens up local development on Apple Silicon MacBooks, which currently isn't documented/supported at all.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with DEVELOPMENT.md, ./forge vms start, ./setup-environment, the Vagrantfile/vars, and development/roles/. Compare the requested Linux flow with forklift's roles/vagrant and determine the separate macOS Apple Silicon path, command naming, provider-specific boxes, and privilege handling. Done means an opt-in host setup command supports the stated Linux and macOS cases and the setup flow is documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, devops, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100