diff --git a/docs/user-guide/boxes.md b/docs/user-guide/boxes.md new file mode 100644 index 000000000..3c01f188b --- /dev/null +++ b/docs/user-guide/boxes.md @@ -0,0 +1,65 @@ +--- +layout: guide +title: User Guide - Boxes +--- +# Boxes + +A Vagrant "box" is the term used to describe a packaged Vagrant +environment. A box is a portable file which can be used by others +to quickly get a virtual environment up and running. A box must +contain the necessary files for the VirtualBox VM and may optionally +include a Vagrantfile. + +Boxes are also required as a base for all vagrant projects. The +`vagrant box` utility provides all the power for managing boxes. +`vagrant package` is used to create a box from a vagrant project. + +## Installing a Box + +Boxes can be installed from the filesystem or via HTTP (note that +if you're interested, its quite easy to extend this to support more +protocols). No matter the source, the installation method is the same. +The following adds a box named `ubuntu_base` to a local vagrant +installation: + +{% highlight bash %} +$ vagrant box add ubuntu_base http://files.vagrantup.com/base.box +{% endhighlight %} + +The name used with the `vagrant box add` command is the name used to +reference the box from that point forward. Any box can be named anything +you want. + +**Note:** The default Vagrantfile created with `vagrant init` defaults to +using a box named "base." This is why in the getting started guide, the +first few commands tell you to add a box named "base" to the project. + +## Removing a Box + +Boxes can just as easily be removed using the same `vagrant box` command. +The following command removes the `ubuntu_base` box which was added in the +previous section: + +{% highlight bash %} +$ vagrant box remove ubuntu_base +{% endhighlight %} + +**Warning:** There is no going back from this command. This command literally +deletes the files off the filesystem. + +## Creating a Box + +Boxes are created from a vagrant project. So the first step to creating a box +is to setup a project the way you want. Add provisioning, share folders, +etc. Anything you need to get your environment in the correct state. Once +there, just run `vagrant package` and it'll package the environment and +save it to `package.box` in the current working directory. + +Note that `vagrant package` will not include the Vagrantfile or any files other +than the exported virtual machine. If you wish to include additional files, +use the `--include` option. An example below: + +{% highlight bash %} +# We want to include a Vagrantfile into this box +$ vagrant package --include Vagrantfile +{% endhighlight %}