This commit is contained in:
Fabio Rehm
parent
2296d35251
commit
29a4c3c45e
5 changed files with 86 additions and 54 deletions
|
|
@ -2,6 +2,15 @@
|
|||
|
||||
BACKWARDS INCOMPATIBILITY:
|
||||
|
||||
- Plugin activation is now triggered by the `cache.scope` config and that config
|
||||
is now required. Previous versions of the plugin had it set to `:box` but
|
||||
there is no consensus whether `:box` and `:machine` is better. This is to
|
||||
highlight that you need to think about the caching strategy you are going
|
||||
to use. For more information and to discuss this move please check [GH-17](https://github.com/fgrehm/vagrant-cachier/issues/17).
|
||||
- Because `cache.scope` is now a requirement and in order to reduce the amount of
|
||||
configuration required by the plugin, we enabled automatic bucket detection by
|
||||
default. To revert to the old behavior you can disable it globally from your
|
||||
`~/.vagrant.d/Vagrantfile`.
|
||||
- Support for Vagrant < 1.4 is gone, please use a previous plugin version if
|
||||
you are running Vagrant 1.2 / 1.3
|
||||
- Automatic handling of multiple machine scoped cache dirs from versions
|
||||
|
|
|
|||
|
|
@ -17,15 +17,13 @@ vagrant plugin install vagrant-cachier
|
|||
|
||||
## Quick start
|
||||
|
||||
The easiest way to set things up is just to enable [cache buckets auto detection](http://fgrehm.viewdocs.io/vagrant-cachier/usage)
|
||||
from within your `Vagrantfile`:
|
||||
|
||||
```ruby
|
||||
Vagrant.configure("2") do |config|
|
||||
config.vm.box = 'your-box'
|
||||
if Vagrant.has_plugin?("vagrant-cachier")
|
||||
# Enable cache buckets auto detection
|
||||
config.cache.auto_detect = true
|
||||
# Configure cached packages to be shared between instances of the same base box.
|
||||
# More info on http://fgrehm.viewdocs.io/vagrant-cachier/usage
|
||||
config.cache.scope = :box
|
||||
|
||||
# If you are using VirtualBox, you might want to use that to enable NFS for
|
||||
# shared folders. This is also very useful for vagrant-libvirt if you want
|
||||
|
|
|
|||
|
|
@ -24,12 +24,9 @@ from within your `Vagrantfile`:
|
|||
Vagrant.configure("2") do |config|
|
||||
config.vm.box = 'your-box'
|
||||
if Vagrant.has_plugin?("vagrant-cachier")
|
||||
# Enable cache buckets auto detection
|
||||
config.cache.auto_detect = true
|
||||
|
||||
# You can pass in extra mount options for your cache buckets
|
||||
# from http://docs.vagrantup.com/v2/synced-folders/basic_usage.html
|
||||
config.cache.synced_folder_opts = { create: true }
|
||||
# Configure cached packages to be shared between instances of the same base box.
|
||||
# More info on the "Usage" link above
|
||||
config.cache.scope = :box
|
||||
|
||||
# If you are using VirtualBox, you might want to use that to enable NFS for
|
||||
# shared folders. This is also very useful for vagrant-libvirt if you want
|
||||
|
|
|
|||
102
docs/usage.md
102
docs/usage.md
|
|
@ -1,24 +1,76 @@
|
|||
# Usage
|
||||
|
||||
## Auto detect supported cache buckets
|
||||
## Being nice to others
|
||||
|
||||
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_.
|
||||
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.
|
||||
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")
|
||||
config.cache.auto_detect = true
|
||||
# ... vagrant-cachier configs ...
|
||||
end
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
|
||||
By adding the code below to
|
||||
your `Vagrantfile` you can enable automatic detection of supported cache _buckets_.
|
||||
|
||||
This will make .
|
||||
|
||||
## Enable buckets as needed
|
||||
|
||||
|
|
@ -57,40 +109,6 @@ end
|
|||
Please referer to http://docs.vagrantup.com/v2/synced-folders/basic_usage.html for
|
||||
more information about the supported parameters.
|
||||
|
||||
## 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 we might implement a `vagrant cache stats` command that will give you that
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
|
|||
spec.version = VagrantPlugins::Cachier::VERSION
|
||||
spec.authors = ["Fabio Rehm"]
|
||||
spec.email = ["fgrehm@gmail.com"]
|
||||
spec.description = %q{Speed up vagrant boxes provisioning}
|
||||
spec.description = %q{Caffeine reducer}
|
||||
spec.summary = spec.description
|
||||
spec.homepage = "https://github.com/fgrehm/vagrant-cachier"
|
||||
spec.license = "MIT"
|
||||
|
|
@ -17,4 +17,14 @@ Gem::Specification.new do |spec|
|
|||
spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
|
||||
spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
|
||||
spec.require_paths = ["lib"]
|
||||
|
||||
spec.post_install_message = %q{
|
||||
If you are new to vagrant-cachier just follow along with the docs available
|
||||
at http://fgrehm.viewdocs.io/vagrant-cachier.
|
||||
|
||||
If you are a long time user, please note that plugin has gone through many
|
||||
backwards incompatible changes since 0.6.0 so checkout
|
||||
https://github.com/fgrehm/vagrant-cachier/blob/master/CHANGELOG.md
|
||||
before continuing and caching all the things :)
|
||||
}
|
||||
end
|
||||
|
|
|
|||
Loading…
Reference in a new issue