glenux/vagrant-cachier-ng
glenux/vagrant-cachier-ng
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Merge pull request #64 from fgrehm/docs

Browse source 
Yes we have Docs!!!!
This commit is contained in:
Fabio Rehm 2013-12-12 08:10:12 -08:00
parent 1862eeca61 d8e195bb63
commit 354c9ca2b5
17 changed files with 625 additions and 280 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

284
README.md
View file

@ -15,9 +15,9 @@ Make sure you have Vagrant 1.2+ and run:
vagrant plugin install vagrant-cachier
```
## Usage
## Quick start
The easiest way to set things up is just to enable [cache buckets auto detection](#auto-detect-supported-cache-buckets)
The easiest way to set things up is just to enable [cache buckets auto detection](http://fgrehm.viewdocs.io/vagrant-cachier/cache-buckets-auto-detection)
from within your `Vagrantfile`:
```ruby
@ -29,7 +29,8 @@ Vagrant.configure("2") do |config|
end
```
For more information about available buckets, please see the [configuration section](#configurations) below.
For more information please read the documentation available at
http://fgrehm.viewdocs.io/vagrant-cachier.
## Compatible providers
@ -39,283 +40,6 @@ For more information about available buckets, please see the [configuration sect
* [VMware providers](http://www.vagrantup.com/vmware) with NFS enabled (See
[GH-24](https://github.com/fgrehm/vagrant-cachier/issues/24) for more info)
## How does it work?
Right now the plugin does not make any assumptions for you and you have to
configure things properly from your `Vagrantfile`. Please have a look at
the [available cache buckets](#available-cache-buckets) section below for more
information.
Under the hood, the plugin will monkey patch `Vagrant::Builtin::Provision` and
will set things up for each configured cache bucket before running each defined
provisioner and after all provisioners are done. Before halting the machine,
it will revert the changes required to set things up by hooking into calls to
`Vagrant::Builtin::GracefulHalt` so that you can repackage the machine for others
to use without requiring users to install the plugin as well.
Cache buckets will be available from `/tmp/vagrant-cachier` on your guest and
the appropriate folders will get symlinked to the right path _after_ the machine is
up but _right before_ it gets provisioned. We _could_ potentially do it on one go
and share bucket's folders directly to the right path if we were only using VirtualBox
since it shares folders _after_ booting the machine, but the LXC provider does that
_as part of_ the boot process (shared folders are actually `lxc-start` parameters)
and as of now we are not able to get some information that this plugin requires
about the guest machine before it is actually up and running.
Please keep in mind that this plugin won't do magic, if you are compiling things
during provisioning or manually downloading packages that does not fit into a
"cache bucket" you won't see that much of improvement.
## Benchmarks / shameless plug
Please have a look at [this blog post](http://fabiorehm.com/blog/2013/05/24/stop-wasting-bandwidth-with-vagrant-cachier#show_me_the_numbers)
for the numbers I've got down here.
## Configurations
### Auto detect supported cache buckets
As described on the usage section above, you can enable automatic detection of
supported [cache "buckets"](#available-cache-buckets) by adding the code below to
your `Vagrantfile`:
```ruby
Vagrant.configure("2") do |config|
# ...
config.cache.auto_detect = true
end
```
This will make vagrant-cachier do its best to find out what is supported on the
guest machine and will set buckets accordingly.
### Cache scope
By default downloaded packages will get stored on a folder scoped to base boxes
under your `$HOME/.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'
end
```
The cached files will be stored under `$HOME/.vagrant.d/cache/some-box`.
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'
config.cache.scope = :machine
end
```
This will tell vagrant-cachier to download packages to `.vagrant/machines/<machine-name>/cache`
on your current project directory.
### Available cache "buckets"
#### System package managers
##### APT
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-debian-box'
config.cache.enable :apt
end
```
Used by Debian-like Linux distros, will get configured under guest's `/var/cache/apt/archives`.
_Please note that to avoid re-downloading packages, you should avoid `apt-get clean`
as much as possible in order to make a better use of the cache, even if you are
packaging a box_
##### Zypper
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-suse-box'
config.cache.enable :zypper
end
```
Used by SuSE guests, will get configured under guest's `/var/cache/zypp/packages`. It will
also [make sure](lib/vagrant-cachier/bucket/zypper.rb#L20) that `keep-packages` is enabled
for all repositories.
###### Yum
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-centos-box'
config.cache.enable :yum
end
```
Used by CentOS guests, will get configured under guest's `/var/cache/yum`. It will
also [make sure](lib/vagrant-cachier/bucket/yum.rb#L20) that `keepcache` is set to
`1` on guest's `/etc/yum.conf`.
##### Pacman
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-arch-linux-box'
config.cache.enable :pacman
end
```
Used by Arch Linux, will get configured under guest's `/var/cache/pacman/pkg`.
#### Chef
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-box-using-chef-provisioner'
config.cache.enable :chef
end
```
When a Chef provisioner is detected, this bucket caches the default
`file_cache_path` directory, `/var/chef/cache`. Requires Vagrant 1.2.4+.
#### RubyGems
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-box-with-ruby-installed'
config.cache.enable :gem
end
```
Compatible with probably with any type of guest distro, will hook into the `cache`
folder under the result of running `gem env gemdir` as the default SSH user (usualy
`vagrant`) on your guest. If you use rbenv / rvm on the guest machine, make sure
it is already installed before enabling the bucket, otherwise you won't benefit
from this plugin.
#### RVM
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-box-with-rvm-installed'
config.cache.enable :rvm
end
```
Compatible with probably with any type of linux guest distro, will hook into the `cache`
folder under the result of running `rvm info` as the default SSH user (usualy
`vagrant`) on your guest. If you use rvm on the guest machine, make sure
it is already installed before enabling the bucket, otherwise you won't benefit
from this plugin.
#### [npm](https://npmjs.org/)
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-box-with-nodejs-installed'
config.cache.enable :npm
end
```
Compatible with probably any type of linux guest distro, will hook into npm's
cache directory under the result of running `npm config get cache` as
the default SSH user (usually `vagrant`) on your guest.
If you use
[nvm](https://github.com/creationix/nvm) / [n](https://github.com/visionmedia/n)
on the guest machine, make sure it is already installed before enabling
the bucket, otherwise you won't benefit from this plugin.
#### [Composer](http://getcomposer.org/)
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-box-with-php-installed'
config.cache.enable :composer
end
```
Compatible with probably any type of linux guest distro, will cache guests'
`$HOME/.composer` if PHP is detected.
##### APT-CACHER
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-debian-box'
config.cache.enable :apt_cacher
end
```
This is useful, if you are using containers inside your VMs, e.g VirtualBox -> LXC.
This would allow you to reuse packages without sharing folder inside VirtualBox. Only
works with NFS-shared folders (since `vboxsf` is enforcing `vagrant`-user and `apt-cacher`
is running under `apt-cacher-ng` user)
# install apt-cacher on (Host)-VM
$ sudo apt-get install apt-cacher-ng
# get the IP for eth0 interface
$ ifconfig eth0 |grep "inet addr"|awk '{print $2}' |cut -c6-20
# configure mirror on for your docker/LXC instances:
$ echo 'Acquire::http { Proxy "http://X.X.X.X:3142"; };' > /etc/apt/apt.conf.d/10mirror
# check, if working by tailing log on (Host)-VM, while installing packages on (Guest)-VMs
$ tail -f /var/log/apt-cacher-ng/apt-cacher.log
Used by Debian-like Linux distros, will get configured under guest's `/var/cache/apt-cacher-ng`.
## Finding out disk space used by buckets
_TODO_
```shell
$ vagrant cache stats
```
## Cleaning up cache buckets
_TODO_
```shell
$ vagrant cache clean apt
```
## Development
If you want to install the plugin from sources:
```bash
git clone https://github.com/fgrehm/vagrant-cachier.git
cd vagrant-cachier
bundle install
bundle exec rake build
vagrant plugin install pkg/vagrant-cachier-VERSION.gem
```
There are also some [Bats](https://github.com/sstephenson/bats) tests that basically
acts as a [sanity check](spec/acceptance/sanity_check.bats) that you can run with
`bats spec/acceptance` in case you are planning to submit a Pull Request :) Just
keep in mind that it might take a while to run if you are using the default
VirtualBox provider.
## Contributing

28
docs/benchmarks.md Normal file
View file

@ -0,0 +1,28 @@
# Benchmarks
During the early days of this plugin, [@fgrehm](https://github.com/fgrehm) wrote
a [blog post](http://fabiorehm.com/blog/2013/05/24/stop-wasting-bandwidth-with-vagrant-cachier#show_me_the_numbers)
with some benchmarks on the time that was cut down by using the plugin. If you
are interested on the numbers only, the VMs tested were one of vagrant-lxc's
Ubuntu [dev boxes](https://github.com/fgrehm/vagrant-lxc/wiki/Development#using-virtualbox-for-development),
[rails-dev-box](https://github.com/rails/rails-dev-box), his own [rails-base-box](https://github.com/fgrehm/rails-base-box)
and Discourse's [dev box](https://github.com/discourse/discourse/blob/master/Vagrantfile)
| | First provision | Second provision | Diff. | APT cache |
| --- | :---: | :---: | :---: | :---: |
| rails-dev-box | 4m45s | 3m20s | ~29% | 66mb |
| rails-base-box | 11m56s | 7m54s | ~34% | 77mb |
| vagrant-lxc | 10m16s | 5m9s | ~50% | 124mb |
| discourse | 1m41s | 49s | ~51% | 62mb |
<br>
_Please note that the tests were made on May 24th 2013 and nowadays they might
be a bit different_
<br>
Some people have shared their numbers on Twitter and had experienced even better
results:
<blockquote><p>Holy cow... If you dig Vagrant, and like time - you need Vagrant Cachier. 60% speed increase for me. <a href="https://t.co/225jRH7bDa">https://t.co/225jRH7bDa</a> <a href="https://twitter.com/vagrantup">@vagrantup</a></p>&mdash; Chris Rickard (@chrisrickard) <a href="https://twitter.com/chrisrickard/statuses/400128294479081472">November 12, 2013</a></blockquote>
<blockquote><p>vagrant-cachier saved 3:20 off my <a href="https://twitter.com/search?q=%23vagrant&amp;src=hash">#vagrant</a> <a href="https://twitter.com/search?q=%23provisioning&amp;src=hash">#provisioning</a> <a href="http://t.co/VzRRu1QEwL">http://t.co/VzRRu1QEwL</a></p>&mdash; Joe Ferguson (@svpernova09) <a href="https://twitter.com/svpernova09/statuses/400040517943037952">November 11, 2013</a></blockquote>
<blockquote><p>Tested vagrant-cachier. Saved 60% of vagrant up time installing 10 rpms with chef. Pretty awesome. Check it out! <a href="https://t.co/HfbLJNP7GH">github.com/fgrehm/vagrant…</a></p>&mdash; Miguel. (@miguelcnf) <a href="https://twitter.com/miguelcnf/status/343757107058847746">June 9, 2013</a></blockquote>
<blockquote><p>vagrant-cachier took my vagrant spin up from 30 to 5 minutes and reduced my caffeine intake by 3 cups <a href="http://t.co/V0uYpr3U0y">http://t.co/V0uYpr3U0y</a></p>&mdash; Russell Cardullo (@russellcardullo) <a href="https://twitter.com/russellcardullo/statuses/343070870744494080">June 7, 2013</a></blockquote>

30
docs/buckets/apt-cacher.md Normal file
View file

@ -0,0 +1,30 @@
# APT-CACHER
Used by Debian-like Linux distros, will get configured under guest's `/var/cache/apt-cacher-ng`
and only works with NFS-shared folders since `vboxsf` is enforcing `vagrant`-user and `apt-cacher`
is running under `apt-cacher-ng` user.
To manually enable it:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-debian-box'
config.cache.enable :apt_cacher
end
```
One use case for this bucket is if you are using containers inside your VMs, e.g
VirtualBox -> LXC. This would allow you to reuse packages without sharing folder
inside VirtualBox:
# install apt-cacher on (Host)-VM
$ sudo apt-get install apt-cacher-ng
# get the IP for eth0 interface
$ ifconfig eth0 |grep "inet addr"|awk '{print $2}' |cut -c6-20
# configure mirror on for your docker/LXC instances:
$ echo 'Acquire::http { Proxy "http://X.X.X.X:3142"; };' > /etc/apt/apt.conf.d/10mirror
# check, if working by tailing log on (Host)-VM, while installing packages on (Guest)-VMs
$ tail -f /var/log/apt-cacher-ng/apt-cacher.log

17
docs/buckets/apt.md Normal file
View file

@ -0,0 +1,17 @@
# APT
Used by Debian-like Linux distros, will get configured under guest's `/var/cache/apt/archives`.
To manually enable it:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-debian-box'
config.cache.enable :apt
end
```
_Please note that to avoid re-downloading packages, you should avoid `apt-get clean`
as much as possible in order to make a better use of the cache, even if you are
packaging a box since the downloaded packages are actually stored on the host
machine._

13
docs/buckets/chef.md Normal file
View file

@ -0,0 +1,13 @@
# Chef
When a Chef provisioner is detected, this bucket caches the default
`file_cache_path` directory, `/var/chef/cache`. Requires Vagrant 1.2.4+.
To manually enable it:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-box-using-chef-provisioner'
config.cache.enable :chef
end
```

13
docs/buckets/composer.md Normal file
View file

@ -0,0 +1,13 @@
# [Composer](http://getcomposer.org/)
Compatible with probably any type of linux guest distro, will cache guests'
`$HOME/.composer` if PHP is detected.
To manually enable it:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-box-with-php-installed'
config.cache.enable :composer
end
```

18
docs/buckets/npm.md Normal file
View file

@ -0,0 +1,18 @@
# [npm](https://npmjs.org/)
Compatible with probably any type of linux guest distro, will hook into npm's
cache directory under the result of running `npm config get cache` as
the default SSH user (usually `vagrant`) on your guest.
To manually enable it:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-box-with-nodejs-installed'
config.cache.enable :npm
end
```
If you use [nvm](https://github.com/creationix/nvm) / [n](https://github.com/visionmedia/n)
on the guest machine, make sure it is already installed before enabling
the bucket, otherwise you won't benefit from this plugin.

12
docs/buckets/pacman.md Normal file
View file

@ -0,0 +1,12 @@
# Pacman
Used by Arch Linux, will get configured under guest's `/var/cache/pacman/pkg`.
To manually enable it:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-arch-linux-box'
config.cache.enable :pacman
end
```

22
docs/buckets/rubygems.md Normal file
View file

@ -0,0 +1,22 @@
# RubyGems
Compatible with probably with any type of guest distro, will hook into the `cache`
folder under the result of running `gem env gemdir` as the default SSH user (usualy
`vagrant`) on your guest. If you use rbenv / rvm on the guest machine, make sure
it is already installed before enabling the bucket, otherwise you won't benefit
from this plugin.
To manually enable it:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-box-with-ruby-installed'
config.cache.enable :gem
end
```
## Heads up about `bundle install --deployment`
Please note that when the `--deployment` flag is passed on to `bundle install`
your gems **will not be cached** since bundler ends up skipping the default gem
cache dir. For more information about this, please check [GH-62](https://github.com/fgrehm/vagrant-cachier/issues/62).

59
docs/buckets/rvm.md Normal file
View file

@ -0,0 +1,59 @@
# [rvm](https://rvm.io/)
Compatible with probably with any type of linux guest distro, will hook into the
`cache` folder under the result of running rvm info as the default SSH user (usualy
`vagrant`) on your guest. If you use rvm on the guest machine, make sure it is
already installed before enabling the bucket, otherwise you won't benefit from
this plugin.
To manually enable it:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-box-with-rvm-installed'
config.cache.enable :gem
end
```
## Heads up!
If you are installing rvm, rubies and gems on a single provisioning step, **you
will not benefit from this bucket**. There is absolutely no way we can "magically"
hook into your provisioning scripts to configure things for leveraging the cache.
For instance, the following shell provisioner **will result in no package cached at
all**:
```ruby
config.vm.provision :shell, privileged: false, inline: %[
curl -L https://get.rvm.io | bash -s stable
rvm install 1.9.3
rvm use 1.9.3 --default
cd /path/to/project
bundle install
]
```
To work around that you can either configure things by hand on your provisioning
scripts or you can enable automatic bucket detection and split your scripts into
multiple stages:
```ruby
# Install RVM so that Ruby tarballs are cached
config.vm.provision :shell, privileged: false, inline: %[
curl -L https://get.rvm.io | bash -s stable
]
# Install Ruby 1.9.3 making use of the RVM cache and configure the RubyGems
# cache afterwards
config.vm.provision :shell, privileged: false, inline: %[
rvm install 1.9.3
rvm use 1.9.3 --default
]
# Install gems making use of the RubyGems cache
config.vm.provision :shell, privileged: false, inline: %[
cd /path/to/project
bundle install
]
```

14
docs/buckets/yum.md Normal file
View file

@ -0,0 +1,14 @@
# Yum
Used by CentOS guests, will get configured under guest's `/var/cache/yum`. It will
also [make sure](lib/vagrant-cachier/bucket/yum.rb#L20) that `keepcache` is set to
`1` on guest's `/etc/yum.conf`.
To manually enable it:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-centos-box'
config.cache.enable :yum
end
```

14
docs/buckets/zypper.md Normal file
View file

@ -0,0 +1,14 @@
# Zypper
Used by SuSE guests, will get configured under guest's `/var/cache/zypp/packages`. It will
also [make sure](lib/vagrant-cachier/bucket/zypper.rb#L20) that `keep-packages` is enabled
for all repositories.
To manually enable it:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'some-suse-box'
config.cache.enable :zypper
end
```

64
docs/development.md Normal file
View file

@ -0,0 +1,64 @@
# Development
## Installing from sources
If you want to install the plugin from sources:
```bash
git clone https://github.com/fgrehm/vagrant-cachier.git
cd vagrant-cachier
bundle install
bundle exec rake build
vagrant plugin install pkg/vagrant-cachier-VERSION.gem
```
## Sanity checks
While we don't get to implement some proper unit testing, there are some basic [Bats](https://github.com/sstephenson/bats)
tests that basically acts as a [sanity check](https://github.com/fgrehm/vagrant-cachier/blob/master/spec/acceptance/sanity_check.bats)
that you can run with `bats spec/acceptance` in case you are planning to submit a
Pull Request. Just keep in mind that it might take a while to run if you are
using the default VirtualBox provider.
## How to create a new bucket?
The concept of a cache _bucket_ is pretty easy to understand, we basically
symlink a folder under the guest's `/tmp/vagrant-cache` into the folder where
other tools keep downloaded packages. For example, in the case of the
[apt bucket](buckets/apt), we symlink `/var/cache/apt/archives` to
`/tmp/vagrant-cache/apt` so that `.deb` packages downloaded with `apt-get install`
can be reused when bringing machines up from scratch.
If you want to see some other package manager supported, you'll first need to
know if it has some sort of caching in place, where does it get stored and if
it needs some extra configuration. For some managers that path will be fixed
(like the canonical apt bucket), for others you might need to read some
configuration by [running a command](https://github.com/fgrehm/vagrant-cachier/blob/master/lib/vagrant-cachier/cap/linux/rvm_path.rb#L10)
on the guest VM (like [rvm](buckets/rvm)) and you might even need to [tweak some configs](https://github.com/fgrehm/vagrant-cachier/blob/master/lib/vagrant-cachier/bucket/yum.rb#L20)
on the guest (like the [yum](buckets/yum) bucket).
There's currently a lot of duplication around the "installation" of cache buckets
so there's plenty of source code for you to read in order to understand how
things work under the hood but if you don't feel comfortable reading / writing
Ruby code you can provide a high level overview of how to do things using plain
old bash.
For example, if you were to explain how to set up the rvm bucket, the script
below should give vagrant-cachier maintainers an overview of how to set things
up:
```bash
# Check is rvm is installed
if ! $(rvm info > /dev/null); then
exit 0
fi
# If it is installed, read the cache dir
RVM_CACHE="${rvm_path}/archives"
# "Install" the bucket!
mkdir -p /tmp/vagrant-cache/rvm/archives
ln -s /tmp/vagrant-cache/rvm/archives $RVM_CACHE
```

32
docs/how-does-it-work.md Normal file
View file

@ -0,0 +1,32 @@
## How does it work?
On vagrant-cachier's _"jargon"_, cached packages are kept in _cache buckets_.
Those _buckets_ are basically directories that are shared between the host machine
and VMs that are kept around between `vagrant destroy`s. Each _bucket_ (or synced
folder if you prefer) is meant to cache specific types of packages, like [apt](buckets/apt)'s
`.deb`s or [RubyGems](buckets/rubygems) `.gem`s. Please have a look at the
"Available Buckets" menu above for more information on each bucket.
Regarding configurations, right now the plugin does not make any assumptions for
you and you have to configure things properly from your `Vagrantfile`. In other
words, _the plugin is disabled by default_.
Cache buckets will always be available from `/tmp/vagrant-cachier` on your guest and
the appropriate folders will get symlinked to the right path _after_ the machine is
up but _right before_ it gets provisioned. We _could_ potentially do it on one go
and share bucket's folders directly to the right path if we were only using VirtualBox
because it shares folders _after_ booting the machine but the LXC provider does that
_as part of_ the boot process (synced folders are actually `lxc-start` parameters)
and as of now we are not able to get some information that this plugin requires
about the guest machine / container before it is actually up and running.
Under the hood, the plugin will monkey patch `Vagrant::Builtin::Provision` and
will set things up for each configured cache bucket _before and after_ running each
defined provisioner. Before halting the machine, it will also revert the changes
required to set things up by hooking into calls to `Vagrant::Builtin::GracefulHalt`
so that you can repackage the machine for others to use without requiring users to
install the plugin as well.
Please keep in mind that this plugin won't do magic, if you are compiling things
during provisioning or manually downloading packages outside of a bucket you
won't see that much of improvement.

49
docs/index.md Normal file
View file

@ -0,0 +1,49 @@
# vagrant-cachier
A [Vagrant](http://www.vagrantup.com/) plugin that helps you reduce the amount of
coffee you drink while waiting for boxes to be provisioned by sharing a common
package cache among similiar VM instances. Kinda like [vagrant-apt_cache](https://github.com/avit/vagrant-apt_cache)
or [this magical snippet](http://gist.github.com/juanje/3797297) but targetting
multiple package managers and Linux distros.
## Installation
Make sure you have Vagrant 1.2+ and run:
```
vagrant plugin install vagrant-cachier
```
## Quick start
The easiest way to set things up is just to enable [cache buckets auto detection](usage)
from within your `Vagrantfile`:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = 'your-box'
config.cache.auto_detect = true
# If you are using VirtualBox, you might want to enable NFS for shared folders
# config.cache.enable_nfs = true
end
```
For more information please check out the links on the menu above.
## Compatible providers
* Vagrant's built in VirtualBox provider
* [vagrant-lxc](https://github.com/fgrehm/vagrant-lxc)
* [VMware providers](http://www.vagrantup.com/vmware) with NFS enabled (See
[GH-24](https://github.com/fgrehm/vagrant-cachier/issues/24) for more info)
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request

137
docs/template.html Normal file
View file

@ -0,0 +1,137 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>{{NAME}} :: viewdocs.io</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta charset="utf-8">
<link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootswatch/3.0.2/yeti/bootstrap.min.css">
<link rel="stylesheet" href="http://fgrehm.github.io/viewdocs-yeti/stylesheets/pygment_trac.css">
<style>
html, body {
height: 100%;
margin: 0;
padding: 0;
/* The html and body elements cannot have any padding or margin. */
}
/* Wrapper for page content to push down footer */
#wrap {
min-height: 100%;
height: auto;
/* Negative indent footer by its height */
margin: 0 auto -60px;
/* Pad bottom by footer height */
padding: 0 0 60px;
}
/* Set the fixed height of the footer here */
footer {
height: 60px;
background-color: #f5f5f5;
padding-top: 9px;
}
footer p {
clear: left;
margin-bottom: 0;
}
#wrap > .container {
padding-top: 60px;
}
.navbar-nav>li>iframe {
margin-top: 12px;
}
th {
padding: 10px;
}
</style>
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
</head>
<body>
<div id="wrap">
<div class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<a href="/{{NAME}}" class="navbar-brand">{{NAME}}</a>
<button class="navbar-toggle" type="button" data-toggle="collapse" data-target="#navbar-main">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<div class="navbar-collapse collapse" id="navbar-main">
<ul class="nav navbar-nav">
<li>
<a href="usage">Usage</a>
</li>
<li>
<a href="how-does-it-work">How does it work?</a>
</li>
<li>
<a href="benchmarks">Benchmarks</a>
</li>
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Available Buckets <span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a tabindex="-1" href="buckets/apt">APT</a></li>
<li><a tabindex="-1" href="buckets/apt-cacher">apt-cacher</a></li>
<li><a tabindex="-1" href="buckets/chef">Chef</a></li>
<li><a tabindex="-1" href="buckets/composer">Composer</a></li>
<li><a tabindex="-1" href="buckets/pacman">Pacman</a></li>
<li><a tabindex="-1" href="buckets/npm">npm</a></li>
<li><a tabindex="-1" href="buckets/rubygems">RubyGems</a></li>
<li><a tabindex="-1" href="buckets/rvm">rvm</a></li>
<li><a tabindex="-1" href="buckets/yum">Yum</a></li>
<li><a tabindex="-1" href="buckets/zypper">Zypper</a></li>
</ul>
</li>
<li>
<a href="development">Development</a>
</li>
</ul>
<ul class="nav navbar-nav navbar-right visible-md visible-lg">
<li><iframe src="http://ghbtns.com/github-btn.html?user={{USER}}&repo={{NAME}}&type=watch&count=true" allowtransparency="true" frameborder="0" scrolling="0" width="110" height="20"></iframe></li>
<li><iframe src="http://ghbtns.com/github-btn.html?user={{USER}}&repo={{NAME}}&type=fork&count=true" allowtransparency="true" frameborder="0" scrolling="0" width="95" height="20"></iframe></li>
</ul>
</div>
</div>
</div>
<div class="container">
{{CONTENT}}
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="col-lg-12">
<p>Hosted on <a href="http://viewdocs.io">http://viewdocs.io</a>.</p>
<p>Theme based on <a href="http://bootswatch.com/yeti/">Yeti</a> built by <a href="http://thomaspark.me">Thomas Park</a> and adapted to Viewdocs by <a href="http://fabiorehm.com/">Fábio Rehm</a>.</p>
</div>
</div>
</div>
</footer>
<script src="//oss.maxcdn.com/libs/jquery/2.0.3/jquery.min.js"></script>
<script src="//netdna.bootstrapcdn.com/bootstrap/3.0.3/js/bootstrap.min.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-38687494-5', 'viewdocs.io');
ga('send', 'pageview');
</script>
</body>
</html>

99
docs/usage.md Normal file
View file

@ -0,0 +1,99 @@
# Usage
## Auto detect supported cache buckets
This is the easiest way to get started with plugin. By adding the code below to
your `Vagrantfile` you can enable automatic detection of supported cache _buckets_:
```ruby
Vagrant.configure("2") do |config|
# ...
config.cache.auto_detect = true
end
```
This will make vagrant-cachier do its best to find out what is supported on the
guest machine and will set buckets accordingly.
## 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.enable :apt
config.cache.enable :gem
end
```
_Please refer to the "Available Buckets" menu above to find out which buckets
are supported._
## Cache scope
By default downloaded packages will get stored on a folder scoped to base boxes
under your `$HOME/.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'
config.cache.auto_detect = true
end
```
The cached files will be stored under `$HOME/.vagrant.d/cache/some-box`.
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'
config.cache.scope = :machine
end
```
This will tell vagrant-cachier to download packages to `.vagrant/machines/<machine-name>/cache`
on your current project directory.
## Finding out disk space used by buckets
At some point there'll be 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 there'll be 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/cache/<box-name>/<optional-bucket-name>
```