Merge pull request #20 from bowlofeggs/vagrant

Add a basic page for Vagrant.

docs/index.rst

@@ -19,6 +19,7 @@ Contents:
    atomiccommandcheatsheet
    base
    docker
+   vagrant
    irssi
    contribute
 

docs/vagrant.rst

@@ -0,0 +1,91 @@
+=======
+Vagrant
+=======
+
+`Vagrant <https://www.vagrantup.com/>`_ is a useful development tool that lowers the barrier to
+entry to new contributors of your project. With Vagrant, new contributors don't have to spend much
+time configuring their development environment, but can quickly get one automatically provisioned
+for them with a few simple commands.
+
+Using Vagrant in Fedora
+=======================
+
+Fedora's Cloud working group provides Fedora Vagrant boxes for libvirt and Virtualbox. You can see
+the Fedora 24 Vagrant images
+`here <https://download.fedoraproject.org/pub/fedora/linux/releases/24/CloudImages/x86_64/images/>`_.
+
+To quickly get started with Vagrant on a Fedora host, the Fedora developers have conveniently
+packaged vagrant-libvirt and a handful of handy Vagrant plugins for you. All you need to do is to
+install vagrant-libvirt and the plugins you wish to use, write a Vagrantfile for your project, and
+type "vagrant up" to get started. Here's an example Vagrantfile::
+
+ $ cat Vagrantfile
+ # -*- mode: ruby -*-
+ # vi: set ft=ruby :
+ 
+ # On your host:
+ # git clone https://github.com/fedora-infra/bodhi.git
+ # cd bodhi
+ # cp Vagrantfile.example Vagrantfile
+ # vagrant up
+ # vagrant ssh -c "cd /vagrant/; pserve development.ini --reload"
+ 
+ Vagrant.configure(2) do |config|
+   config.vm.box_url = "https://download.fedoraproject.org/pub/fedora/linux/releases/24/CloudImages/x86_64/images/Fedora-Cloud-Base-Vagrant-24-1.2.x86_64.vagrant-libvirt.box"
+   config.vm.box = "f24-cloud-libvirt"
+   config.vm.network "forwarded_port", guest: 80, host: 80
+   config.vm.synced_folder ".", "/vagrant", type: "sshfs"
+ 
+   config.vm.provider :libvirt do |domain|
+       domain.cpus = 4
+       domain.graphics_type = "spice"
+       domain.memory = 1024
+       domain.video_type = "qxl"
+   end
+ 
+   config.vm.provision "shell", inline: "echo hello_world > /home/vagrant/hello_world.txt"
+ 
+   # Uncomment the following block if you have a playbook at devel/ansible/playbook.yml you want Vagrant to run on the guest for you
+   # # Ansible needs the guest to have these
+   # config.vm.provision "shell", inline: "sudo dnf install -y libselinux-python python2-dnf"
+   #
+   # config.vm.provision "ansible" do |ansible|
+   #     ansible.playbook = "devel/ansible/playbook.yml"
+   # end
+ end
+
+In this example, we're using the Fedora 24 libvirt box and we're assuming that your project has an
+ansible playbook at the relative path ``devel/ansible/playbook.yml``. Writing ansible playbooks is
+beyond the scope of this document, and you are free to use config.vm.provision lines to configure
+your Vagrant guest if you like.
+
+To get started with the above example, simply write the code to a file called Vagrantfile, install
+``vagrant-libvirt`` and ``vagrant-sshfs``, and run ``vagrant up``::
+
+ $ cd ~/devel/my_project
+ $ vim Vagrantfile  # Write the above Vagrant code here
+ $ sudo dnf install vagrant-libvirt vagrant-sshfs
+ $ vagrant up
+
+Once your guest is running, you can ssh into the guest. Your code directory from the host will be
+shared into the guest at the path ``/vagrant``::
+
+ $ vagrant ssh
+ $ [vagrant@localhost ~]$ ls /vagrant/Vagrantfile
+ /vagrant/Vagrantfile
+
+Now you can edit your project on your host, and the changes you make will be shared into the guest's
+``/vagrant`` folder live. This allows you to use your editor of choice (even graphical editors!) on
+the host, while keeping everything that might "dirty" you host system contained in the guest virtual
+machine. This example ``Vagrantfile`` has also set up a port forward from 80 in the guest to 80 on
+the host, so if there were a web application listening in the guest on port 80, you could browse to
+http://localhost on the host to access it.
+
+When you are done with your Vagrant guest, you can destroy it::
+
+ $ vagrant destroy
+
+It is good practice to check in a ``Vagrantfile.example`` file in your project's source code, rather
+than the ``Vagrantfile`` itself. This allows new developers a quick way to get started by just
+copying your example into place, but it also allows each contributor to make the changes they prefer
+to their individual Vagrantfiles.