Add Vagrantfile, documentation

Document suggested workflow in CONTRIBUTING.md
Other minor improvements to contributing documentation

Author: danieldreier

CONTRIBUTING.md

@@ -3,20 +3,67 @@ Testing
 
 Tests on the puppet-puppet module can be run via `rake`.
 
-Run beaker acceptance tests:
+#### Beaker acceptance tests
 ```
-BEAKER_destroy=no BEAKER_provision=no rake acceptance
+BEAKER_destroy=no BEAKER_provision=onpass rake acceptance
 ```
 
 Run beaker acceptance tests on debian 7:
 ```
-BEAKER_set=debian-73-x64 BEAKER_destroy=no BEAKER_provision=no rake acceptance
+BEAKER_set=debian-73-x64 BEAKER_destroy=onpass BEAKER_provision=no rake acceptance
 ```
 See spec/acceptance/nodesets for a list of possible node names; use the filename without .yml.
 
-Run rspec-puppet tests:
+If a beaker test fails, you can SSH into the environment if you use BEAKER_PROVISION=onpass.
+The path of the vagrantfile will be `.vagrant/beaker_vagrant_files/debian-73-x64.yml`
+if you followed the above instructions, and slightly different if you used a
+different nodeset. `cd` to that directory and `vagrant ssh` to access the VM.
+The tests that ran are in /tmp with randomly generated filenames.
+```
+
+#### rspec-puppet tests
 (note that these are run automatically by travis CI on pull requests)
 ```
 rake spec
 ```
 
+Vagrant
+=======
+
+This project includes a Vagrantfile to facilitate development. The purpose of
+the Vagrantfile is to give you an easy way to interactively edit code and run
+tests without polluting your workstation, and without having to worry about
+deploying code constantly to test minor changes.
+
+The recommended way to use this for iteratively working out changes is:
+```
+rm -rf pkg
+rake build
+vagrant up shared_folder
+vagrant ssh shared_folder
+```
+
+This will build a new package you could upload to puppetforge in the pkg
+directory. Vagrant will use that to install dependencies, but will mount the
+repository to /etc/puppet/modules/puppet so your changes take effect
+immediately.
+
+A second vagrant environment exists for testing packages prior to puppetforge
+release. A typical workflow might be:
+```bash
+rm -rf pkg
+rake build
+vagrant up package_install
+vagrant ssh package_install
+```
+
+Once in one of these systems, the tests in /vagrant/tests may be helpful for
+testing during development.
+
+Finally, an agent VM is provided to help test client-server interaction:
+
+```bash
+vagrant up agent
+vagrant ssh agent
+sudo puppet agent --test --waitforcert 10 --server puppet
+```

Vagrantfile

@@ -0,0 +1,71 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+VAGRANTFILE_API_VERSION = "2"
+
+Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
+    ### Define options for all VMs ###
+    # Using vagrant-cachier improves performance if you run repeated yum/apt updates
+    if defined? VagrantPlugins::Cachier
+      config.cache.auto_detect = true
+    end
+    config.ssh.forward_agent = true
+
+    config.vm.provider :virtualbox do |vb|
+      vb.customize ["modifyvm", :id, "--memory", "512", "--cpus", "4", "--ioapic", "on"]
+    end
+    # hack to avoid ubuntu/debian-specific 'stdin: is not a tty' error on startup
+    config.ssh.shell = "bash -c 'BASH_ENV=/etc/profile exec bash'"
+
+    # distro-agnostic puppet install script from https://github.com/danieldreier/puppet-installer
+    config.vm.provision "shell", inline: "curl getpuppet.whilefork.com | bash"
+
+    PUPPETMASTER_IP = '192.168.37.23'
+
+    config.vm.define :package_install do |node|
+      node.vm.box = 'puppetlabs/debian-7.4-64-nocm'
+      node.vm.hostname = 'debian7.boxnet'
+      node.vm.network :private_network, ip: PUPPETMASTER_IP
+
+      # hack to avoid ubuntu/debian-specific 'stdin: is not a tty' error on startup
+      node.ssh.shell = "bash -c 'BASH_ENV=/etc/profile exec bash'"
+
+      # distro-agnostic puppet install script from https://github.com/danieldreier/puppet-installer
+      node.vm.provision "shell", inline: "curl getpuppet.whilefork.com | bash"
+
+      # use a packaged version of puppet-puppet to install dependencies via the forge
+      # rm removes symlink from next step for vagrant provision idempotency
+      node.vm.provision "shell",
+        inline: "rm -rf /etc/puppet/modules/puppet"
+      node.vm.provision "shell",
+        inline: "if ls /vagrant/pkg/ploperations-puppet-*.tar.gz ; then puppet module install /vagrant/pkg/ploperations-puppet-*.tar.gz; fi"
+    end
+
+    config.vm.define :shared_folder do |node|
+      node.vm.box = 'puppetlabs/debian-7.4-64-nocm'
+      node.vm.hostname = 'debian7.boxnet'
+      node.vm.network :private_network, ip: PUPPETMASTER_IP
+
+      # use a packaged version of puppet-puppet to install dependencies via the forge
+      # rm removes symlink from next step for vagrant provision idempotency
+      node.vm.provision "shell",
+        inline: "rm -rf /etc/puppet/modules/puppet"
+      node.vm.provision "shell",
+        inline: "if ls /vagrant/pkg/ploperations-puppet-*.tar.gz ; then puppet module install /vagrant/pkg/ploperations-puppet-*.tar.gz; rm -rf /etc/puppet/modules/puppet; fi"
+
+      # if this was done as a vagrant shared folder, the previous step either
+      # wouldn't run or would overwrite files this approach allows using
+      # puppet's facilities for installing dependencies while also keeping a
+      # shared folder to simplify development
+      node.vm.provision "shell",
+        inline: "ln -s /vagrant /etc/puppet/modules/puppet"
+    end
+
+    config.vm.define :agent do |node|
+      node.vm.box = 'puppetlabs/debian-7.4-64-nocm'
+      node.vm.hostname = 'debian7agent.boxnet'
+      node.vm.network :private_network, ip: "192.168.37.25"
+      node.vm.provision "shell",
+        inline: "if ! grep #{PUPPETMASTER_IP} /etc/hosts; then echo '#{PUPPETMASTER_IP} puppet' >> /etc/hosts; fi"
+    end
+end