From fc6819ce00e974f9b8d316278ad1e5b09da65855 Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 02:04:41 -0200 Subject: [PATCH 01/18] Import viewdocs-yeti layout --- docs/template.html | 130 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 docs/template.html diff --git a/docs/template.html b/docs/template.html new file mode 100644 index 0000000..5cc5b97 --- /dev/null +++ b/docs/template.html @@ -0,0 +1,130 @@ + + + + {{NAME}} :: viewdocs.io + + + + + + + + + + + + +
+
+
+
+ {{NAME}} + +
+ +
+
+ +
+ {{CONTENT}} +
+
+ + + + + + + + From eb544ae7730392bb57fdaa03c7d1de88d7779ac8 Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 02:10:11 -0200 Subject: [PATCH 02/18] docs index --- docs/index.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/index.md diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..ddedf92 --- /dev/null +++ b/docs/index.md @@ -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](config/auto-detection) +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 From 94de55a2413eb24d51491f94bd8942f5e6ea5b9b Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 02:42:49 -0200 Subject: [PATCH 03/18] docs: How does it work? --- docs/how-does-it-work.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/how-does-it-work.md diff --git a/docs/how-does-it-work.md b/docs/how-does-it-work.md new file mode 100644 index 0000000..80a8f5d --- /dev/null +++ b/docs/how-does-it-work.md @@ -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. From 2734186347d54f37484f1b4c0b3f3675cdd779f4 Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 03:09:28 -0200 Subject: [PATCH 04/18] Benchmarks --- docs/benchmarks.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/benchmarks.md diff --git a/docs/benchmarks.md b/docs/benchmarks.md new file mode 100644 index 0000000..c0fa86d --- /dev/null +++ b/docs/benchmarks.md @@ -0,0 +1,30 @@ +# 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 projects tested were one of vagrant-lxc's +Ubuntu [dev box](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 | +
+_Please note that the tests were made on May 24th 2013 and nowadays they might +be a bit different_ + +
+Some people have shared their numbers on Twitter and had experienced even better +results: + +

Holy cow... If you dig Vagrant, and like time - you need Vagrant Cachier. 60% speed increase for me. https://t.co/225jRH7bDa @vagrantup

— Chris Rickard (@chrisrickard) November 12, 2013
+

vagrant-cachier saved 3:20 off my #vagrant #provisioning http://t.co/VzRRu1QEwL

— Joe Ferguson (@svpernova09) November 11, 2013
+

Tested vagrant-cachier. Saved 60% of vagrant up time installing 10 rpms with chef. Pretty awesome. Check it out! github.com/fgrehm/vagrant…

— Miguel. (@miguelcnf) June 9, 2013
+

vagrant-cachier took my vagrant spin up from 30 to 5 minutes and reduced my caffeine intake by 3 cups http://t.co/V0uYpr3U0y

— Russell Cardullo (@russellcardullo) June 7, 2013
From 94ba773ce6479203ae517ca083ce78626283498b Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 03:26:36 -0200 Subject: [PATCH 05/18] docs: usage --- docs/usage.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/usage.md diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..d90db94 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,86 @@ +# Usage + +## Configurations + +### 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. + +### 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//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/fabio/.vagrant.d/cache/precise64 +1.1G /home/fabio/.vagrant.d/cache/raring64 +448M /home/fabio/.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// + +# scope = :machine +$ rm -rf .vagrant/cache// +``` From 00f4aaa28ca8c12824cd10e6bdfce26001a9f634 Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 03:43:37 -0200 Subject: [PATCH 06/18] docs for buckets --- docs/buckets/apt-cacher.md | 29 +++++++++++++++++++++++++++++ docs/buckets/apt.md | 14 ++++++++++++++ docs/buckets/chef.md | 11 +++++++++++ docs/buckets/composer.md | 11 +++++++++++ docs/buckets/npm.md | 16 ++++++++++++++++ docs/buckets/pacman.md | 10 ++++++++++ docs/buckets/rubygems.md | 14 ++++++++++++++ docs/buckets/rvm.md | 14 ++++++++++++++ docs/buckets/yum.md | 12 ++++++++++++ docs/buckets/zypper.md | 12 ++++++++++++ docs/template.html | 5 +++++ 11 files changed, 148 insertions(+) create mode 100644 docs/buckets/apt-cacher.md create mode 100644 docs/buckets/apt.md create mode 100644 docs/buckets/chef.md create mode 100644 docs/buckets/composer.md create mode 100644 docs/buckets/npm.md create mode 100644 docs/buckets/pacman.md create mode 100644 docs/buckets/rubygems.md create mode 100644 docs/buckets/rvm.md create mode 100644 docs/buckets/yum.md create mode 100644 docs/buckets/zypper.md diff --git a/docs/buckets/apt-cacher.md b/docs/buckets/apt-cacher.md new file mode 100644 index 0000000..440b2e4 --- /dev/null +++ b/docs/buckets/apt-cacher.md @@ -0,0 +1,29 @@ +# 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`. + diff --git a/docs/buckets/apt.md b/docs/buckets/apt.md new file mode 100644 index 0000000..780892b --- /dev/null +++ b/docs/buckets/apt.md @@ -0,0 +1,14 @@ +# 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_ diff --git a/docs/buckets/chef.md b/docs/buckets/chef.md new file mode 100644 index 0000000..2ead6e9 --- /dev/null +++ b/docs/buckets/chef.md @@ -0,0 +1,11 @@ +# 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+. diff --git a/docs/buckets/composer.md b/docs/buckets/composer.md new file mode 100644 index 0000000..33f229d --- /dev/null +++ b/docs/buckets/composer.md @@ -0,0 +1,11 @@ +# [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. diff --git a/docs/buckets/npm.md b/docs/buckets/npm.md new file mode 100644 index 0000000..fadca00 --- /dev/null +++ b/docs/buckets/npm.md @@ -0,0 +1,16 @@ +# [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. diff --git a/docs/buckets/pacman.md b/docs/buckets/pacman.md new file mode 100644 index 0000000..6393d63 --- /dev/null +++ b/docs/buckets/pacman.md @@ -0,0 +1,10 @@ +# 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`. diff --git a/docs/buckets/rubygems.md b/docs/buckets/rubygems.md new file mode 100644 index 0000000..7f58cb4 --- /dev/null +++ b/docs/buckets/rubygems.md @@ -0,0 +1,14 @@ +# 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. diff --git a/docs/buckets/rvm.md b/docs/buckets/rvm.md new file mode 100644 index 0000000..e244309 --- /dev/null +++ b/docs/buckets/rvm.md @@ -0,0 +1,14 @@ +# [rvm](https://rvm.io/) + +```ruby +Vagrant.configure("2") do |config| + config.vm.box = 'some-box-with-rvm-installed' + config.cache.enable :gem +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. diff --git a/docs/buckets/yum.md b/docs/buckets/yum.md new file mode 100644 index 0000000..4b3182b --- /dev/null +++ b/docs/buckets/yum.md @@ -0,0 +1,12 @@ +# 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`. diff --git a/docs/buckets/zypper.md b/docs/buckets/zypper.md new file mode 100644 index 0000000..7c8131f --- /dev/null +++ b/docs/buckets/zypper.md @@ -0,0 +1,12 @@ +# 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. diff --git a/docs/template.html b/docs/template.html index 5cc5b97..6c8ee0e 100644 --- a/docs/template.html +++ b/docs/template.html @@ -44,6 +44,11 @@ .navbar-nav>li>iframe { margin-top: 12px; } + + table { + margin-left: auto; + margin-right: auto; + } From 03b2b801219d3ba6c9edb851fff504777f911145 Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 03:50:47 -0200 Subject: [PATCH 07/18] docs on development --- docs/development.md | 47 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/development.md diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..9fb5e15 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,47 @@ +# 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 + +There are also some [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 simple 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](https://github.com/fgrehm/vagrant-cachier#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](https://github.com/fgrehm/vagrant-cachier#rvm)) and you might even 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](https://github.com/fgrehm/vagrant-cachier#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 +``` From 0340d6e76b7d36e940bded66a7aa9ac43bb9e2e9 Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 03:51:10 -0200 Subject: [PATCH 08/18] docs: Adjust menu --- docs/template.html | 43 +++++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/docs/template.html b/docs/template.html index 6c8ee0e..8e7014f 100644 --- a/docs/template.html +++ b/docs/template.html @@ -71,35 +71,38 @@ From 3c4a20f44d324ff4abbd6c61da0176fa6193a9f5 Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 03:54:03 -0200 Subject: [PATCH 09/18] Hide github badges on smaller screens --- docs/template.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/template.html b/docs/template.html index 8e7014f..4f4f6c4 100644 --- a/docs/template.html +++ b/docs/template.html @@ -100,7 +100,7 @@ -
    +
    From 16b68e72f17a0d307304287f76ac045136b03d26 Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 12:36:03 -0200 Subject: [PATCH 10/18] Improve buckets docs --- docs/benchmarks.md | 4 ++-- docs/buckets/apt-cacher.md | 17 +++++++++-------- docs/buckets/apt.md | 9 ++++++--- docs/buckets/chef.md | 8 +++++--- docs/buckets/composer.md | 8 +++++--- docs/buckets/npm.md | 10 ++++++---- docs/buckets/pacman.md | 6 ++++-- docs/buckets/rubygems.md | 14 ++++++++------ docs/buckets/rvm.md | 14 ++++++++------ docs/buckets/yum.md | 10 ++++++---- docs/buckets/zypper.md | 10 ++++++---- docs/index.md | 2 +- docs/usage.md | 21 +++++++++++++++++---- 13 files changed, 83 insertions(+), 50 deletions(-) diff --git a/docs/benchmarks.md b/docs/benchmarks.md index c0fa86d..03b9e82 100644 --- a/docs/benchmarks.md +++ b/docs/benchmarks.md @@ -3,8 +3,8 @@ 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 projects tested were one of vagrant-lxc's -Ubuntu [dev box](https://github.com/fgrehm/vagrant-lxc/wiki/Development#using-virtualbox-for-development), +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) diff --git a/docs/buckets/apt-cacher.md b/docs/buckets/apt-cacher.md index 440b2e4..23ce21a 100644 --- a/docs/buckets/apt-cacher.md +++ b/docs/buckets/apt-cacher.md @@ -1,5 +1,11 @@ # 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' @@ -7,10 +13,9 @@ Vagrant.configure("2") do |config| 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) +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 @@ -23,7 +28,3 @@ is running under `apt-cacher-ng` user) # 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`. - diff --git a/docs/buckets/apt.md b/docs/buckets/apt.md index 780892b..dba1220 100644 --- a/docs/buckets/apt.md +++ b/docs/buckets/apt.md @@ -1,5 +1,9 @@ # 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' @@ -7,8 +11,7 @@ Vagrant.configure("2") do |config| 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_ +packaging a box since the downloaded packages are actually stored on the host +machine._ diff --git a/docs/buckets/chef.md b/docs/buckets/chef.md index 2ead6e9..20dd354 100644 --- a/docs/buckets/chef.md +++ b/docs/buckets/chef.md @@ -1,11 +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 ``` - -When a Chef provisioner is detected, this bucket caches the default -`file_cache_path` directory, `/var/chef/cache`. Requires Vagrant 1.2.4+. diff --git a/docs/buckets/composer.md b/docs/buckets/composer.md index 33f229d..2aafedb 100644 --- a/docs/buckets/composer.md +++ b/docs/buckets/composer.md @@ -1,11 +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 ``` - -Compatible with probably any type of linux guest distro, will cache guests' -`$HOME/.composer` if PHP is detected. diff --git a/docs/buckets/npm.md b/docs/buckets/npm.md index fadca00..d7f3200 100644 --- a/docs/buckets/npm.md +++ b/docs/buckets/npm.md @@ -1,5 +1,11 @@ # [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' @@ -7,10 +13,6 @@ Vagrant.configure("2") do |config| 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. diff --git a/docs/buckets/pacman.md b/docs/buckets/pacman.md index 6393d63..360a86c 100644 --- a/docs/buckets/pacman.md +++ b/docs/buckets/pacman.md @@ -1,10 +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 ``` - -Used by Arch Linux, will get configured under guest's `/var/cache/pacman/pkg`. diff --git a/docs/buckets/rubygems.md b/docs/buckets/rubygems.md index 7f58cb4..ffdf8cc 100644 --- a/docs/buckets/rubygems.md +++ b/docs/buckets/rubygems.md @@ -1,14 +1,16 @@ # 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 ``` - -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. diff --git a/docs/buckets/rvm.md b/docs/buckets/rvm.md index e244309..a216323 100644 --- a/docs/buckets/rvm.md +++ b/docs/buckets/rvm.md @@ -1,14 +1,16 @@ # [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 ``` - -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. diff --git a/docs/buckets/yum.md b/docs/buckets/yum.md index 4b3182b..8788d2b 100644 --- a/docs/buckets/yum.md +++ b/docs/buckets/yum.md @@ -1,12 +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 ``` - -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`. diff --git a/docs/buckets/zypper.md b/docs/buckets/zypper.md index 7c8131f..2cea5c5 100644 --- a/docs/buckets/zypper.md +++ b/docs/buckets/zypper.md @@ -1,12 +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 ``` - -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. diff --git a/docs/index.md b/docs/index.md index ddedf92..189e48e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,7 +17,7 @@ vagrant plugin install vagrant-cachier ## Quick start -The easiest way to set things up is just to enable [cache buckets auto detection](config/auto-detection) +The easiest way to set things up is just to enable [cache buckets auto detection](usage) from within your `Vagrantfile`: ```ruby diff --git a/docs/usage.md b/docs/usage.md index d90db94..214cb81 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,8 +1,6 @@ # Usage -## Configurations - -### Auto detect supported cache buckets +## 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_: @@ -17,7 +15,22 @@ 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 +## 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 From fb978209932f1095b7a1f55e79fc2783da6aea74 Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 12:36:38 -0200 Subject: [PATCH 11/18] Remove docs from readme --- README.md | 284 +----------------------------------------------------- 1 file changed, 4 insertions(+), 280 deletions(-) diff --git a/README.md b/README.md index 32c382b..92f8041 100644 --- a/README.md +++ b/README.md @@ -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//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 From c4ba0c944537f54e15dc73a3c4045376f0c2df1a Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 12:36:55 -0200 Subject: [PATCH 12/18] Remove my name from output :P --- docs/usage.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 214cb81..c393f05 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -73,9 +73,9 @@ if you are on a Linux machine: ``` # scope = :box (default) $ du -h -d0 $HOME/.vagrant.d/cache -405M /home/fabio/.vagrant.d/cache/precise64 -1.1G /home/fabio/.vagrant.d/cache/raring64 -448M /home/fabio/.vagrant.d/cache/quantal64 +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 From 54407fd2dadd657454b9518b75f800abc41e3694 Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 12:43:49 -0200 Subject: [PATCH 13/18] Improve dev docs --- docs/development.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/development.md b/docs/development.md index 9fb5e15..0c30650 100644 --- a/docs/development.md +++ b/docs/development.md @@ -15,22 +15,39 @@ vagrant plugin install pkg/vagrant-cachier-VERSION.gem ## Sanity checks -There are also some [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) +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 +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 simple 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](https://github.com/fgrehm/vagrant-cachier#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. +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](https://github.com/fgrehm/vagrant-cachier#rvm)) and you might even 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](https://github.com/fgrehm/vagrant-cachier#yum) bucket) +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. +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: +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 From 5a488a2972992cab698a8d0f2e72a55644a0ce8e Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 12:47:34 -0200 Subject: [PATCH 14/18] Heads up about `bundle install --deployment` Closes GH-62 --- docs/buckets/rubygems.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/buckets/rubygems.md b/docs/buckets/rubygems.md index ffdf8cc..4396259 100644 --- a/docs/buckets/rubygems.md +++ b/docs/buckets/rubygems.md @@ -14,3 +14,9 @@ Vagrant.configure("2") do |config| 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). From 27788c995ccca8046a84816c9cfc16437b0ade43 Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 12:57:39 -0200 Subject: [PATCH 15/18] Document rvm gotchas Closes GH-43 --- docs/buckets/rvm.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/buckets/rvm.md b/docs/buckets/rvm.md index a216323..f19ac49 100644 --- a/docs/buckets/rvm.md +++ b/docs/buckets/rvm.md @@ -14,3 +14,46 @@ Vagrant.configure("2") do |config| 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 +] +``` From 3421b4489a1d40f5858d6288f49405a3399e55ba Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Sat, 7 Dec 2013 13:01:24 -0200 Subject: [PATCH 16/18] Fix GA tracking code --- docs/template.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/template.html b/docs/template.html index 4f4f6c4..78d253e 100644 --- a/docs/template.html +++ b/docs/template.html @@ -131,7 +131,7 @@ (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-4', 'viewdocs.io'); + ga('create', 'UA-38687494-5', 'viewdocs.io'); ga('send', 'pageview'); From b28ac072a5b15f65c60e8bf12949b57c389efc66 Mon Sep 17 00:00:00 2001 From: Mark Steve Samson Date: Sun, 8 Dec 2013 09:24:13 +0800 Subject: [PATCH 17/18] Make menu links relative --- docs/template.html | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/template.html b/docs/template.html index 78d253e..4a79e20 100644 --- a/docs/template.html +++ b/docs/template.html @@ -72,31 +72,31 @@