haskal
/
vagrant
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

website/docs: docs for box versioning

This commit is contained in:
Mitchell Hashimoto 2014-01-25 12:18:41 -08:00
parent 7a6d1a3ff1
commit 286a503cb6
8 changed files with 325 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
website/docs/Vagrantfile vendored Normal file
View File

@ -0,0 +1,23 @@
# -*- mode: ruby -*-
# vi: set ft=ruby :
# Vagrantfile API/syntax version. Don't touch unless you know what you're doing!
VAGRANTFILE_API_VERSION = "2"
$script = <<SCRIPT
sudo apt-get -y update
sudo apt-get -y install curl
curl -sSL https://get.rvm.io | bash -s stable
. ~/.bashrc
. ~/.bash_profile
rvm install 2.0.0
rvm --default use 2.0.0
cd /vagrant
bundle
SCRIPT
Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
config.vm.box = "precise64"
config.vm.network "private_network", ip: "33.33.33.10"
config.vm.provision "shell", inline: $script, privileged: false
end

1
website/docs/source/layouts/layout.erb
View File

@ -139,6 +139,7 @@
<li<%= sidebar_current("boxes") %>><a href="/v2/boxes.html">Boxes</a></li>
<% if sidebar_section == "boxes" %>
<ul class="sub unstyled">
<li<%= sidebar_current("boxes-versioning") %>><a href="/v2/boxes/versioning.html">Box Versioning</a></li>
<li<%= sidebar_current("boxes-base") %>><a href="/v2/boxes/base.html">Creating a Base Box</a></li>
<li<%= sidebar_current("boxes-format") %>><a href="/v2/boxes/format.html">Box File Format</a></li>
</ul>

2
website/docs/source/stylesheets/_base.less
View File

@ -87,7 +87,7 @@ h6 {
}
p, td {
letter-spacing: 0.05em;
letter-spacing: normal;
line-height: 32px;
a {

92
website/docs/source/v2/boxes.html.md
View File

@ -5,74 +5,44 @@ sidebar_current: "boxes"
# Boxes
Boxes are the skeleton from which Vagrant machines are constructed. They are
portable files which can be used by others on any platform that runs Vagrant
to bring up a working environment.
Boxes are the package format for Vagrant environments. A box can be used by
anyone on any platform that Vagrant supports to bring up an identical
working environment.
The `vagrant box` utility provides all the functionality for managing
boxes. Boxes must currently be created manually.
boxes. You can read the documentation on the [vagrant box](/v2/cli/box.html)
command for more information.
Boxes are [provider-specific](/v2/providers/index.html), so you must obtain
the proper box depending on what provider you're using.
The easiest way to use a box is to add a box from the
[publicly available catalog of Vagrant boxes](#).
You can also add and share your own customized boxes on this website.
If you're interested in more details on the exact file format of
boxes, there is a separate [page dedicated to that](/v2/boxes/format.html), since
it is an advanced topic that general users don't need to know.
Boxes also support versioning so that members of your team using Vagrant
can update the underlying box easily, and the people who create boxes
can push fixes and communicate these fixes efficiently.
## Adding Boxes
You can learn all about boxes by reading this page as well as the
sub-pages in the navigation to the left.
Adding boxes is straightforward:
## Discovering Boxes
The easiest way to find boxes is to look on the
[public Vagrant box catalog](#)
for a box matching your use case. The catalog contains most major operating
systems as bases, as well as specialized boxes to get you up and running
quickly with LAMP stacks, Ruby, Python, etc.
The boxes on the public catalog work with many different
[providers](/v2/providers/index.html). Whether you're using Vagrant with
VirtualBox, VMware, AWS, etc. you should be able to find a box you need.
Adding a box from the catalog is very easy. Each box shows you instructions
with how to add it, but they all follow the same format:
```
$ vagrant box add name url
$ vagrant box add USER/BOX
...
```
`name` is a logical name by which the box is referenced from the
Vagrantfile. You can put anything you want here, but know that Vagrant
matches the `config.vm.box` directive with this name in order to look up
the box to use.
`url` is the location of the box. This can be a path to your local filesystem
or an HTTP URL to the box remotely.
Vagrant will automatically determine the provider the box was built
for by reading the "metadata.json" file within the box archive. You
may also tell Vagrant what provider the box is for by specifying the
`--provider` flag.
This is recommended as it adds an extra level of verification
to the box you're downloading. Additionally, Vagrant can exit early with
an error if a box with that name and provider already exists, whereas
it must download the entire box before showing such an error in the other
case.
Multiple boxes with the same name can exist as long as they are all
for different providers. The example of listing boxes below shows this,
where there are multiple precise64 boxes, backed by different providers.
This lets a single `config.vm.box` configuration within a Vagrantfile
properly reference boxes across providers.
## Listing Boxes
To view what boxes Vagrant has locally installed, use `vagrant box list`:
```
$ vagrant box list
precise64 (virtualbox)
precise64 (vmware_fusion)
```
Vagrant lists all boxes along with the providers the box is for in parentheses.
## Removing Boxes
Boxes can be removed just as easily as they are added:
```
$ vagrant box remove precise64 virtualbox
```
The two arguments are the logical name of the box and the provider of the
box. The second argument (the provider) is optional. If you have only a single
provider backing that box, it doesn't need to be specified. If you have multiple
providers backing a box and it isn't specified, Vagrant will show an error.
For example: `vagrant box add hashicorp/precise64`. You can also quickly
initialize a Vagrant environment with `vagrant init hashicorp/precise64`.

9
website/docs/source/v2/boxes/base.html.md
View File

@ -180,6 +180,15 @@ Packaging the box into a `box` file is provider-specific. Please refer to
the provider-specific documentation for creating a base box. Some
provider-specific guides are linked to towards the top of this page.
## Distributing the Box
You can distribute the box file however you'd like. However, if you want
to support versioning, putting multiple providers at a single URL, pushing
updates, analytics, and more, we recommend you add the box to
[Vagrant Cloud](#).
You can upload both public and private boxes to this service.
## Testing the Box
To test the box, pretend you're a new user of Vagrant and give it a shot:

85
website/docs/source/v2/boxes/format.html.md
View File

@ -6,21 +6,82 @@ sidebar_current: "boxes-format"
# Box File Format
In the past, boxes were just [tar files](http://en.wikipedia.org/wiki/Tar_\(computing\))
of VirtualBox exports. With Vagrant supporting multiple providers, box files
are now tar files where the contents differ for each provider. They are
still tar files, but they may now optionally be [gzipped](http://en.wikipedia.org/wiki/Gzip)
as well.
of VirtualBox exports. With Vagrant supporting multiple
[providers](/v2/providers/index.html) and [versioning](/v2/boxes/versioning.html)
now, box files are slightly more complicated.
Box files made for Vagrant 1.0.x and VirtualBox continue to work with
Vagrant 1.1+ and the VirtualBox provider.
Box files made for Vagrant 1.0.x (the VirtualBox export tar files) continue
to work with Vagrant today. When Vagrant encounters one of these old boxes,
it automatically updates it internally to the new format.
The only file required within a box is a "metadata.json" file. This is
a [JSON](http://www.json.org/) file that has a top-level object that
can contain any metadata about the box. Vagrant requires that a "provider"
key exists in this metadata with the name of the provider the box is made
for.
Today, box files are split into two different components:
The "metadata.json" file for a VirtualBox box:
* Box Metadata - This is a JSON document that specifies the name of the box,
a description, available versions, available providers, and URLs to the
actual box files (next component) for each provider and version. If this
metadata doesn't exist, a box file can still be added directly, but it
will not support versioning and updating.
* Box File - This is a compressed (tar, tar.gz, zip) file that is specific
to a single provider and can contain anything. Vagrant core doesn't ever
use the contents of this file. Instead, they are passed to the provider.
Therefore, a VirtualBox box file has different contents from a VMware
box file and so on.
Each component is covered in more detail below.
## Box Metadata
The metadata is an optional component for a box (but highly recommended)
that enables [versioning](/v2/boxes/versioning.html), updating, multiple
providers from a single file, and more.
<div class="alert alert-block alert-info">
<strong>You don't need to manually make the metadata.</strong> If you
have an account with <a href="#">Vagrant Cloud</a>, you
can create boxes there, and Vagrant Cloud automatically creates
the metadata for you. The format is still documented here.
</div>
It is a JSON document, structured in the following way:
```json
{
"name": "hashicorp/precise64",
"description": "This box contains Ubuntu 12.04 LTS 64-bit.",
"versions": [{
"version": "0.1.0",
"providers": [{
"name": "virtualbox",
"url": "http://somewhere.s3.com/precise64_010_virtualbox.box"
}]
}]
}
```
As you can see, the JSON document can describe multiple versions of a box,
multiple providers, and can add/remove providers in different versions.
This JSON file can be passed directly to `vagrant box add` and Vagrant
will install the proper version of the box. If multiple providers are
available, Vagrant will ask what provider you want to use.
## Box File
The actual box file is the required portion for Vagrant. It is recommended
you always use a metadata file alongside a box file, but direct box files
are supported for legacy reasons in Vagrant.
Box files are compressed using tar, tar.gz, or zip. The contents of the
archive can be anything, and is specific to each
[provider](/v2/providers/index.html). Vagrant core itself only unpacks
the boxes for use later.
Within the archive, Vagrant does expect a single file: "metadata.json".
This is a JSON file that is completely unrelated to the above "box metadata"
component. This file must contain at least the "provider" key with the
provider the box is for. For example, if your box was for VirtualBox,
the metadata.json would look like this:
```json
{

95
website/docs/source/v2/boxes/versioning.html.md Normal file
View File

@ -0,0 +1,95 @@
---
page_title: "Box Versioning"
sidebar_current: "boxes-versioning"
---
# Box Versioning
Since Vagrant 1.5, boxes support versioning. This allows the people who
make boxes to push updates to the box, and the people who use the box
have a simple workflow for checking for updates, updating their boxes,
and seeing what has changed.
If you're just getting started with Vagrant, box versioning isn't too
important, and we recommend learning about some other topics first. But
if you're using Vagrant on a team or plan on creating your own boxes,
versioning is very important. Luckily, having versioning built right in
to Vagrant makes it easy to use and fit nicely into the Vagrant workflow.
This page will cover how to use versioned boxes. It does _not_ cover how
to update your own custom boxes with versions. That is covered in
[creating a base box](/v2/boxes/base.html).
## Viewing Versions and Updating
You can view the versions a box has by calling `vagrant box info`. This
command will refresh the metadata associated with a box and list all
available versions for this box. `vagrant box list` only shows _installed_
versions of boxes.
You can check if the box you're using is outdated with `vagrant box outdated`.
This can check if the box in your current Vagrant environment is outdated
as well as any other box installed on the system.
Finally, you can update boxes with `vagrant box update`. This will download
and install the new box. This _will not_ magically update running Vagrant
environments. If a Vagrant environment is already running, you'll have to
destroy and recreate it to acquire the new updates in the box. The update
command just downloads these updates locally.
## Version Constraints
You can constrain a Vagrant environment to a specific version or versions
of a box using the [Vagrantfile](/v2/vagrantfile/index.html) by specifying
the `config.vm.box_version` option.
If this option is not specified, the latest version is always used. This is
equivalent to specifying a constraint of ">= 0".
The box version configuration can be a specific version or a constraint of
versions. Constraints can be any combination of the following:
`= X`, `> X`, `< X`, `>= X`, `<= X`, `~> X`. You can combine multiple
constraints by separating them with commas. All the constraints should be
self explanatory except perhaps for `~>`, known as the "pessimistic constraint".
Examples explain it best: `~> 1.0` is equivalent to `>= 1.0, < 2.0`. And
`~> 1.1.5` is equivalent to `>= 1.1.5, < 1.2.0`.
You can choose to handle versions however you see fit. However, many boxes
in the public catalog follow [semantic versioning](http://semver.org/).
Basically, only the first number (the "major version") breaks backwards
compatibility. In terms of Vagrant boxes, this means that any software that
runs in version "1.1.5" of a box should work in "1.2" and "1.4.5" and so on,
but "2.0" might introduce big changes that break your software. By following
this convention, the best constraint is `~> 1.0` because you know it is safe
no matter what version is in that range.
Of course, you're free to use versions however you'd like!
## Automatic Update Checking
Using the [Vagrantfile](/v2/vagrantfile/index.html), you can also configure
Vagrant to automatically check for updates during any `vagrant up`. This is
disabled by default, but can easily be enabled with
`config.vm.box_check_update = true` in your Vagrantfile.
When this is enabled, Vagrant will check for updates on every `vagrant up`,
not just when the machine is being created from scratch, but also when it
is resuming, starting after being halted, etc.
If an update is found, Vagrant will output a warning to the user letting
them know an update is available. That user can choose to ignore the warning
for now, or can update the box by running `vagrant box update`.
Vagrant can not and does not automatically download the updated box and
update the machine because boxes can be relatively large and updating the
machine requires destroying it and recreating it, which can cause important
data to be lost. Therefore, this process is manual to the extent that the
user has to manually enter a command to do it.
## Pruning Old Versions
Vagrant does not automatically prune old versions because it doesn't know
if they might be in use by other Vagrant environments. Because boxes can
be large, you may want to actively prune them once in awhile using
`vagrant box remove`. You can see all the boxes that are installed
using `vagrant box list`.

115
website/docs/source/v2/cli/box.html.md
View File

@ -13,23 +13,28 @@ The main functionality of this command is exposed via even more subcommands:
* `add`
* `list`
* `outdated`
* `remove`
* `repackage`
* `update`
# Box Add
**Command: `vagrant box add NAME URL`**
**Command: `vagrant box add ADDRESS`**
This adds a box at the given URL to Vagrant and stores it under the
logical name `NAME`.
This adds a box with the given address to Vagrant. The address can be
one of three things:
The URL may be a file path or an HTTP URL. For HTTP, basic authentication
is supported and `http_proxy` environmental variables are respected. HTTPS
is also supported.
* A shorthand name from the
[public catalog of available Vagrant images](#),
such as "hashicorp/precise64".
The name argument of this command is a _logical name_, meaning you can
effectively choose whatever you want. This is the name that Vagrant searches
for to match with the `config.vm.box` setting in Vagrantfiles.
* File path or HTTP URL to a box in a [catalog](#).
For HTTP, basic authentication is supported and `http_proxy` environmental
variables are respected. HTTPS is also supported.
* URL directly a box file. In this case, you must specify a `--name` flag
(see below) and versioning/updates won't work.
If an error occurs during the download or the download is interrupted with
a Ctrl-C, then Vagrant will attempt to resume the download the next time it
@ -38,21 +43,17 @@ after the initial download.
## Options
* `--box-version VALUE` - The version of the box you want to add. By default,
the latest version will be added. The value of this can be an exact version
number such as "1.2.3" or it can be a set of version constraints. A version
constraint looks like ">= 1.0, < 2.0".
* `--cacert CERTFILE` - The certificate for the CA used to verify the peer.
This should be used if the remote end doesn't use a standard root CA.
* `--cert CERTFILE` - A client certificate to use when downloading the box, if
necessary.
* `--checksum VALUE` - A checksum for the box that is downloaded. If specified,
Vagrant will compare this checksum to what is actually downloaded and will
error if the checksums do not match. This is highly recommended since
box files are so large. If this is specified, `--checksum-type` must
also be specified.
* `--checksum-type TYPE` - The type of checksum that `--checksum` is if it
is specified. Supported values are currently "md5", "sha1", and "sha256".
* `--clean` - If given, Vagrant will remove any old temporary files from
prior downloads of the same URL. This is useful if you don't want Vagrant
to resume a download from a previous point, perhaps because the contents
@ -68,23 +69,66 @@ after the initial download.
adding is for the given provider. By default, Vagrant automatically
detects the proper provider to use.
## Options for direct box files
The options below only apply if you're adding a box file directly (when
you're not using a catalog).
* `--checksum VALUE` - A checksum for the box that is downloaded. If specified,
Vagrant will compare this checksum to what is actually downloaded and will
error if the checksums do not match. This is highly recommended since
box files are so large. If this is specified, `--checksum-type` must
also be specified. If you're downloading from a catalog, the checksum is
included within the catalog entry.
* `--checksum-type TYPE` - The type of checksum that `--checksum` is if it
is specified. Supported values are currently "md5", "sha1", and "sha256".
* `--name VALUE` - Logical name for the box. This is the value that you
would put into `config.vm.box` in your Vagrantfile. When adding a box from
a catalog, the name is included in the catalog entry and doesn't have
to be specified.
# Box List
**Command: `vagrant box list`**
This command lists all the boxes that are installed into Vagrant.
# Box Outdated
**Command: `vagrant box outdated`**
This command tells you whether or not the box you're using in
your current Vagrant environment is outdated. If the `--global` flag
is present, every installed box will be checked for updates.
Checking for updates involves refreshing the metadata associated with
a box. This generally requires an internet connection.
## Options
* `--box-info` - If given, Vagrant will display the URL from where the box
has been downloaded and the date it was added
* `--global` - Check for updates for all installed boxes, not just the
boxes for the current Vagrant environment.
# Box Remove
**Command: `vagrant box remove NAME PROVIDER`**
**Command: `vagrant box remove NAME`**
This command removes a box from Vagrant that matches the given name and
provider.
This command removes a box from Vagrant that matches the given name.
If a box has multiple providers, the exact provider must be specified
with the `--provider` flag. If a box has multiple versions, you can select
what versions to delete with the `--box-version` flag.
## Options
* `--box-version VALUE` - Version of version constraints of the boxes to
remove. See documentation on this flag for `box add` for more details.
* `--provider VALUE` - The provider-specific box to remove with the given
name. This is only required if a box is backed by multiple providers.
If there is only a single provider, Vagrant will default to removing it.
# Box Repackage
@ -96,3 +140,28 @@ directory so you can redistribute it.
When you add a box, Vagrant unpacks it and stores it internally. The
original `*.box` file is not preserved. This command is useful for
reclaiming a `*.box` file from an installed Vagrant box.
# Box Update
**Command: `vagrant box update`**
This command updates the box for the current Vagrant environment if there
are updates available. The command can also update a specific box (outside
of an active Vagrant environment), by specifying the `--box` flag.
Note that updating the box will not update an already-running Vagrant
machine. To reflect the changes in the box, you'll have to destroy and
bring back up the Vagrant machine.
If you just want to check if there are updates available, use the
`vagrant box outdated` command.
## Options
* `--box VALUE` - Name of a specific box to update. If this flag is not
specified, Vagrant will update the boxes for the active Vagrant
environment.
* `--provider VALUE` - When `--box` is present, this controls what
provider-specific box to update. This is not required unless the box has
multiple providers. Without the `--box` flag, this has no effect.