Fedora 22 comes with a lot of great features and having Vagrant with libvirt support is one of them. Don’t know what Vagrant is good for? Vagrant is a program that enables you to create portable and reproducible development environments easily supporting many hosts and guests operating systems and various features such as synced folders, forwarded ports and support for famous provisioners such as Chef, Puppet or Ansible. And that’s still not everything. You can configure Vagrant to use Linux containers (Docker support is baked in) or famous cloud services so you don’t even have to run your development virtual machine on your computer.

Installing Vagrant

To install plain Vagrant package, run:

# dnf install vagrant

This will install base Vagrant package which is what you want in case you only need to use Vagrant with Docker or provider that is currently not directly supported in Fedora such as VirtualBox. This is esentially a stripped down Vagrant that does not come with any plugins.

# dnf install vagrant-libvirt

Run the above mentioned command if you wish to use Vagrant with QEMU/KVM virtualization via libvirt (recommended as this is what we can support). It will install base Vagrant package and vagrant-libvirt plugin. If you would also like to avoid typing password everytime you virtualize something from Vagrant, download also vagrant-libvirt-doc sub-package and run the following to allow vagrant group to manage libvirt without authentication:

# dnf install vagrant-libvirt-doc
# cp /usr/share/vagrant/gems/doc/vagrant-libvirt-0.0.26/polkit/10-vagrant-libvirt.rules /usr/share/polkit-1/rules.d/

And finally, if you prefer lxc to Docker, you can install vagrant-lxc plugin as well by running:

# dnf install vagrant-lxc

Vagrant for older Fedoras

Not running Fedora 22 yet? Packages have been already back-ported to Fedora 21 as well and are available for quite some time in the official repositories. And if you are running RHEL or CentOS, look at my Copr repository that contains a vagrant1 software collection.

Upstream packages

We packaged Vagrant as we wanted to see an easier way of installing and using Vagrant in Fedora, especially together with vagrant-libvirt provider. Our packages provide streightforward installation and updates for Vagrant and unlike from the RPMs provided by upstream we do not bundle Vagrant dependencies. This has however one limitation that we are unable to resolve; at the moment we don’t support uploading custom boxes to Atlas (official Vagrant cloud) as we are not shipping an internal Vagrant plugins that provide this functionality. This is due to the fact that upstream decided to use RubyEncoder binaries that we cannot ship in Fedora because of their licensing. Please note that this does not affect downloading images from Atlas. If you need uploading as well, you have to grab and install the upstream package (which is also available as RPM).

Getting started

If you don’t know Vagrant yet, you will need to spend a few minutes understanding how to setup your development environment. The first part is to understant what Vagrant boxes and Vagrantfiles are. Boxes are provider-specific images with some metadata and Vagrantfiles are configuration files of your projects. To set up an environment you need to create a Vagrantfile in the root directory of the project. Here is an example of minimal, rather empty, Vagrantfile:

Vagrant.configure(2) do |config|
  config.vm.box = "fedora-22"

As you can see, Vagrantfile is just a regular Ruby file that let’s you use Vagrant DSL to define your development environment. In our minimal example we set only ‘box’ parameter to define our Vagrant box. With this we can already tell Vagrant to virtualize our new development environment by running vagrant up. Dependending on our default provider (libvirt in Fedora, VirtualBox in upstream), Vagrant will try to create and boot up the virtual machine. It will also configure your environment by few default options like rsyncing your project’s directory to /vagrant on the newly created guest.

This is of course just the beginning. There is really a lot of options how to further set up your project’s development environment and they are mostly provider specific, so read your provider’s documentation just after going through official one. A good start for defining the environment for your first project will be a default Vagrantfile which will be generated for you after running vagrant init. It contains a lot of commented-out options alongside with their descriptions that should help you to define your configuration quickly.

Another great way is to study Vagrantfiles for open-source projects; for instance OpenShift origin has one as well as Ruby on Rails upstream.

Getting a box

As I mentioned above, you won’t make it far without Vagrant boxes. Luckily, Vagrantfiles can be written in a way that fetching boxes happen automatically. This is either because the box is hosted in Atlas and Vagrant would automatically download the boxes from there by matching the username/box pattern, or by specifying config.vm.box_url option in Vagrantfile that sets the URL to the box. Because of this, new project developers don’t need to do more than installing Vagrant, checking out source code with accompying Vagrantfile and running vagrant up. Not to say that they can invoke the command on any supported platform (including various Linuxes, Mac OS and Windows).

In case you need to pick a box for your project, you can find one on Atlas, which is the official place for hosting boxes, or you can already try the upcoming official Fedora Cloud boxes. If you need something specific, you can always build your box from scratch. For that you might find veewee a helpful tool.

Sometimes it’s more convinient to base off your environment on a box with just basic OS installation since it’s easier to get for the others and the maintainence happens only regarding the provisioning process in Vagrantfile, but you can always create a box that is already provisioned and it’s way faster to boot up. For this, vagrant package --output mynew.box command might come in handy, since it can create a new box based on the current, already provisioned, state.

In our minimal example, Vagrant expects a box named ‘fedora-22’ already added. To do so, we can download the prelease box and add it (boxes come with a .box extension, but that’s not a hard requirement):

$ vagrant box add Fedora-Cloud-Base-Vagrant-22-20150521.x86_64.vagrant-libvirt.box --name fedora-22

Development process

Now that we have a minimal Vagrantfile in our project’s directory and box added, we are truly ready to run vagrant up to boot up our machine. Once that finishes, our project’s directory should be available at /vagrant inside our VM. That happened without any configuration, since a few things are default for any Vagrantfile. We are able to change it or add other shared folders later. To log inside we run vagrant ssh to log in as the vagrant user with sudo access (otherwise vagrant ssh-config shows us the IP we need) and we can develop the project as we would normally do on our host.

One thing that you notice is that our shared folder is not automatically synced. Vagrant sync them using rsync only at start up and when running vagrant rsync. To avoid that we can run vagrant rsync-auto which will do the syncing automatically as long as the command keep running. But if you find rsync somehow cumbersome, you can set up NFS, which is way faster.

Our example is completely simplified as Vagrant let’s you create a multi-machine envorinment, set up networking between the nodes, forward ports to host, and more.

Once finished with your changes, just vagrant halt the machine. You can always come back and run vagrant up to bring it back. If you want to remove the VM, run vagrant destroy. Very simple and keeps your host system clean. As it might have crossed your mind, Vagrant VMs are pretty much normal VMs so you can manage them via other software such as virt-manager. That’s true, but Vagrant associates some state with each machine so I suggest to administer them with Vagrant only. You can use virt-manager to open the graphical user interface or remove the domain if you won’t be able to do so using Vagrant though.

More on Vagrant

As this article can’t take you through everything there is about Vagrant, here you can find additinal resources to go though:

And here are people from the Fedora community whose blogs can help you to get up and running with Vagrant on Fedora (please mention yourself in the comments if you blog about Vagrant too):