Skip to content

Add forge subcommand to bootstrap host prerequisites (Vagrant, libvirt / vagrant-qemu) #685

Description

@Odilhao

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    Red Hat Jira

    None yet

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions