1 files changed, 66 insertions, 0 deletions
diff --git a/notes/vagrant.md b/notes/vagrant.md
new file mode 100644
index 000000000..0ef9202f7
--- /dev/null
+++ b/notes/vagrant.md
@@ -0,0 +1,66 @@
+# Using Vagrant
+
+Vagrant provides an easy method to setup virtual development environments, for
+further information see [their website](http://www.vagrantup.com).
+
+The included steps will use vagrant to create a dev environment where you can
+run the test suite, the development server and of course make changes to the
+codebase.
+
+The basic process is to create a "base" vm, and then "provision" it with the
+software packages and setup needed. There are several ways to do this, including
+Chef, Puppet, or the existing FixMyStreet install script which we will use. The
+supplied scripts will create you a Vagrant VM based on the server edition of
+Ubuntu 12.04 LTS that contains everything you need to work on FixMyStreet.
+
+## Pre-requisites
+
+1. Install [VirtualBox](http://www.virtualbox.org/wiki/Downloads)
+2. Install [Vagrant](http://downloads.vagrantup.com/)
+
+## Get the FixMyStreet code
+
+Create a folder somewhere that you'll be doing your work from and clone the repo
+into it.
+
+``` bash
+mkdir FMS-vagrant
+cd FMS-vagrant
+git clone --recursive https://github.com/mysociety/fixmystreet.git
+```
+
+## Set up the Vagrant box
+
+The vagrant configuration needs to be placed in the correct place.
+
+``` bash
+# NOTE - you need to be in the 'FMS-vagrant' dir
+
+cp fixmystreet/conf/Vagrantfile.example Vagrantfile
+
+# start the vagrant box. This will provision the system and can take a long time.
+vagrant up --no-color
+```
+
+## Working with the vagrant box
+
+You should now have a local FixMyStreet development server to work with. You
+can edit the files locally and the changes will be reflected on the virtual
+machine.
+
+To start the dev server:
+
+``` bash
+vagrant ssh
+
+# You are now in a terminal on the virtual machine
+cd /vagrant/fixmystreet
+
+# run the dev server
+bin/cron-wrapper script/fixmystreet_app_server.pl -d -r --fork
+```
+
+The server should now be running and you can visit it at the address
+http://127.0.0.1.xip.io:3000/
+
+Enjoy!