Unison documentation

_layouts/documentation.html

@@ -17,6 +17,7 @@
           <li><a href="/docs/host_only_networking.html">Host-Only Networking</a></li>
           <li><a href="/docs/base_boxes.html">Base Boxes</a></li>
           <li><a href="/docs/systems.html">Systems</a></li>
+          <li><a href="/docs/unison.html">Unison Folder Syncing</a></li>
           <li><a href="/docs/rake.html">Rake Integration</a></li>
         </ol>
       </div>

docs/unison.md

@@ -0,0 +1,94 @@
+---
+layout: documentation
+title: Documentation - Unison Shared Folder Syncing
+---
+# Unison Shared Folder Syncing
+
+Its been a long known issue that VirtualBox shared folder performance
+degrades quickly as the number of files in the shared folder increases.
+As a project reaches thousands of files, doing simple things like running
+unit tests or even just running an app server can be many orders
+of magnitude slower (e.g. from 5 seconds to taking 5 minutes).
+
+If you're seeing this sort of performance drop-off in your shared folders,
+[Unison](http://www.cis.upenn.edu/~bcpierce/unison/) shared folder syncing
+can help! Vagrant will automate a cron job to call `unison` to sync the
+real shared folder with a guest-local folder. You run all your unit tests,
+app server, etc. on the guest-local folder, while the shared folder is
+automatically synced to it.
+
+<div class="info">
+  <h3>The Trade-Off</h3>
+  <p>
+    There is a slight trade-off when using <code>unison</code> folder syncing: There
+    will be a 5 to 10 seconds delay while Unison syncs the folders. So instead
+    of seeing your file changes instantly on the guest, you'll have to wait
+    a few seconds (shouldn't ever be more than 15 seconds), for the changes
+    to propagate.
+  </p>
+  <p>
+    For most people, including myself, this is a fine trade-off instead of
+    waiting 5 minutes for something simple like running a single unit test.
+  </p>
+</div>
+
+## Prerequisites
+
+Before enabling shared folder syncing via unison for any shared folders,
+the guest OS must have [Unison](http://www.cis.upenn.edu/~bcpierce/unison/)
+installed.
+
+Unison is available on most operating systems through their respective
+package managers. For example, on Ubuntu, you can install unison with
+a simple `sudo apt-get install unison`.
+
+Its recommended that you install unison and package that box for the future
+so you don't need to install unison every time you wish to use shared
+folder syncing.
+
+## Enabling Shared Folder Syncing
+
+Shared folder syncing can be enabled by simpling setting a flag on the
+`config.vm.share_folder` method. The example below overrides the default
+root folder sharing to be setup for shared folder syncing:
+
+{% highlight ruby %}
+Vagrant::Config.run do |config|
+  config.vm.share_folder("v-root", "/vagrant", ".", :sync => true)
+end
+{% endhighlight %}
+
+Setting the `:sync` flag will cause that folder to be synced via unison.
+
+## How it Works
+
+When a shared folder is flagged to be synced via Unison, Vagrant will
+append a sync suffix to the end of the guest path (where the shared
+folder will be), and will make Unison sync from that shared folder to
+the actual path you specify.
+
+To make this clear, consider the above example, where the root folder
+was marked to be synced. The steps below are taken:
+
+1. The shared folder is actually mounted to `/vagrant.sync`. This is
+   the typical "slow" VirtualBox shared folder.
+2. Unison is configured on a cron to sync the folder to the original
+   guest path: `/vagrant`.
+3. The syncing script runs in the background constantly (with the cron
+   verifying its running every minute) to sync the two folders. Any
+   app servers, unit test runners, etc, should use the syncced folder:
+   `/vagrant` and _not_ the VirtualBox shared folder.
+
+## Unison Customization
+
+[Unison](http://www.cis.upenn.edu/~bcpierce/unison/) comes with
+[many configurable options](http://www.cis.upenn.edu/~bcpierce/unison/download/releases/stable/unison-manual.html#prefs) and Vagrant does not prevent
+you from setting any of these. You can customize the command line
+parameters to unison via the `config.unison.options` value. Note
+that changing these may cause the syncing to fail or hang. To diagnose
+these failures, check the log files which are typically dumped in
+the user's home directory.
+
+There are other options which are configurable as well. Please see
+the [Vagrantfile](/docs/vagrantfile.html) page for more information
+on these.

docs/vagrantfile.md

@@ -247,3 +247,24 @@ config.chef.run_list = ["recipe[foo]", "recipe[bar]"]
 config.chef.add_recipe("foo")
 config.chef.add_role("bar")
 {% endhighlight %}
+
+## Unison Configuration
+
+If you're using [unison folder syncing](/docs/unison.html), then this
+is configurable with the following options:
+
+`config.unison.folder_suffix` is the string suffix which is appended
+to the original shared folder guest path to be the VirtualBox shared
+folder when configuring sync.
+
+`config.unison.script` is the full path and filename of where to place
+the syncing script.
+
+`config.unison.options` is a string of command line arguments to pass
+to unison when run. By default, these are carefully chosen (and can
+be seen by looking at the `config.rb` file in the Vagrant gem), therefore
+please be careful when modifying these.
+
+`config.unison.crontab_entry_file` is the full path to where the
+unison syncing crontab file is placed.
+