vagrant-cachier-ng/docs/usage.md

# Usage

## Being nice to others

It is a good practice to wrap plugin specific configuration with `has_plugin?` checks
so the user's Vagrantfiles do not break if `vagrant-cachier` is uninstalled or
the Vagrantfile is shared with people that don't have the plugin installed:

```ruby
Vagrant.configure("2") do |config|
  # ...
  if Vagrant.has_plugin?("vagrant-cachier")
    # ... vagrant-cachier configs ...
  end
end
```

## Cache scope

This is the only required configuration for the plugin to work and should be present
on your project's specific `Vagrantfile` or on your `~/.vagrant.d/Vagrantfile` in
order to enable it.

### `:box` scope

By setting `cache.scope` to `:box`, downloaded packages will get stored on a folder
scoped to base boxes under your `~/.vagrant.d/cache`. The idea is to leverage the
cache by allowing downloaded packages to be reused across projects. So, if your
`Vagrantfile` has something like:

```ruby
Vagrant.configure("2") do |config|
  config.vm.box = 'some-box'
  if Vagrant.has_plugin?("vagrant-cachier")
    config.cache.scope = :box
  end
end
```

The cached files will be stored under `$HOME/.vagrant.d/cache/some-box`.

### `:machine` scope

If you are on a [multi VM environment](http://docs.vagrantup.com/v2/multi-machine/index.html),
there is a huge chance that you'll end up having issues by sharing the same bucket
across different machines. For example, if you `apt-get install` from two machines
at "almost the same time" you are probably going to hit a _"SystemError: Failed to
lock /var/cache/apt/archives/lock"_. To work around that, you can set the scope
to be based on machines:

```ruby
Vagrant.configure("2") do |config|
  config.vm.box = 'some-box'
  if Vagrant.has_plugin?("vagrant-cachier")
    config.cache.scope = :machine
  end
end
```

This will tell vagrant-cachier to download packages to `.vagrant/machines/<machine-name>/cache`
on your current project directory.

## Cache buckets automatic detection

This is the easiest way to get started with plugin and is enabled by default.
Under the hood, `vagrant-cachier` does its best to find out what is supported on the
guest machine and will set buckets accordingly.

If you want that behavior to be disabled, you can set `cache.auto_detect` to `false`
from your Vagrantfile:

```ruby
Vagrant.configure("2") do |config|
  config.vm.box = 'some-box'
  if Vagrant.has_plugin?("vagrant-cachier")
    config.cache.scope       = :machine # or :box
    config.cache.auto_detect = false
  end
end
```

## Enable buckets as needed

If for whatever reason you need to have a fined grained control over what buckets
are configured, you can do so by "cherry picking" them on your `Vagrantfile`:

```ruby
Vagrant.configure("2") do |config|
  config.cache.auto_detect = false
  config.cache.enable :apt
  config.cache.enable :gem
end
```

_Please refer to the "Available Buckets" menu above to find out which buckets
are supported._

## Disable buckets in auto-detect mode

If for some reason you need to disable certain buckets but want the remaining
buckets to be configured you can do so by disabling on an individual basis in
your `Vagrantfile`:

```ruby
Vagrant.configure("2") do |config|
  config.cache.auto_detect = true
  config.cache.disable = :chef_gem
end
```

_Please refer to the "Available Buckets" menu above to find out which buckets
are supported._

## Custom cache buckets synced folders options

For fine grained control over the cache bucket synced folder options you can use
the `synced_folder_opts` config. That's useful if, for example, you are using
VirtualBox and want to enable NFS for improved performance:

```ruby
Vagrant.configure("2") do |config|
  config.cache.synced_folder_opts = {
    type: :nfs,
    # The nolock option can be useful for an NFSv3 client that wants to avoid the
    # NLM sideband protocol. Without this option, apt-get might hang if it tries
    # to lock files needed for /var/cache/* operations. All of this can be avoided
    # by using NFSv4 everywhere. Please note that the tcp option is not the default.
    mount_options: ['rw', 'vers=3', 'tcp', 'nolock']
  }
end
```

Please referer to http://docs.vagrantup.com/v2/synced-folders/basic_usage.html for
more information about the supported parameters.

## Finding out disk space used by buckets

At some point we might implement a `vagrant cache stats` command that will give you that
information, but while that does not get implemented you can run the code below
if you are on a Linux machine:

```
# scope = :box (default)
$ du -h -d0 $HOME/.vagrant.d/cache
405M /home/user/.vagrant.d/cache/precise64
1.1G /home/user/.vagrant.d/cache/raring64
448M /home/user/.vagrant.d/cache/quantal64

# scope = :machine
$ du -h -d0 .vagrant/machines/*/cache
16K	 .vagrant/machines/precise/cache
90M	 .vagrant/machines/quantal/cache
210M .vagrant/machines/raring/cache
```

## Cleaning up cache buckets

At some point we might implement a `vagrant cache clean [bucket-name]` command that will
take care of things for you, but while that does not get implemented you can run
the code below if you are on a Linux machine:

```
# scope = :box (default)
$ rm -rf $HOME/.vagrant.d/cache/<box-name>/<optional-bucket-name>

# scope = :machine
$ rm -rf .vagrant/machines/<machine-name>/cache/<optional-bucket-name>
```