94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
---
|
|
layout: getting_started
|
|
title: Getting Started - Boxes
|
|
---
|
|
# Boxes
|
|
|
|
After project initialization, the first step is always to specify the
|
|
_base box_ in the Vagrantfile. Vagrant doesn't create a virtual machine
|
|
instance _completely_ from scratch. Instead, it imports a base image for
|
|
a VM and builds off of that. This simplifes things greatly for Vagrant
|
|
users since they don't have to spend time specifying tedious details
|
|
such as memory capacity, hard disk capacity, network controllers, etc,
|
|
and also allows customizable bases to build projects from.
|
|
|
|
The bases that Vagrant builds off are packaged as "boxes," which are
|
|
basically tar packages in a specific format for Vagrant use. Anybody
|
|
can create a box, and packaging will be covered specifically in the
|
|
[packaging](/docs/getting-started/packaging.html) section.
|
|
|
|
## Getting a Base Box
|
|
|
|
We've already packaged a base box which has a bare bones installation
|
|
of Ubuntu Lucid (10.04) 32-bit. Note that if you already downloaded
|
|
this box from the [overview page](/docs/getting-started/index.html) you
|
|
do not have to download it again.
|
|
|
|
Vagrant supports adding boxes from both the local filesystem and an
|
|
HTTP URL. Begin running the following command so it can begin downloading
|
|
while box installation is covered in more detail:
|
|
|
|
{% highlight bash %}
|
|
$ vagrant box add lucid32 http://files.vagrantup.com/lucid32.box
|
|
{% endhighlight %}
|
|
|
|
Installed boxes reside in `~/.vagrant/boxes`, and they are global to the current vagrant
|
|
installation. This means that once the lucid32 box has been added, it can be used by
|
|
multiple projects at the same time. Each project uses the box as a _base_ only, so once the
|
|
project VM is created, modifications can be made without affecting other
|
|
projects which may use the same box.
|
|
|
|
Note that the box is given its own name, in this case "lucid32." This name
|
|
is used throughout Vagrant to reference that box from this point forward.
|
|
The URL is only used when adding, but never again. And the filename of the
|
|
box means nothing to the logical name given. It is simply a coincidence that
|
|
the filename and logical name are equal in this case.
|
|
|
|
## Removing Boxes
|
|
|
|
Just as easily as they're added, boxes can be removed as well. The following
|
|
is an example command to remove a box.
|
|
|
|
{% highlight bash %}
|
|
$ vagrant box remove my_box
|
|
{% endhighlight %}
|
|
|
|
If you tried to run this command, it will obviously fail, since you haven't
|
|
added a box named "my_box" yet (or if you have, I'm sorry because you just
|
|
deleted it forever).
|
|
|
|
Once a box is removed, no new virtual machines based on that box can be created,
|
|
since it is completely deleted off the filesystem, but existing virtual machines
|
|
which have already been spun up will continue to function properly.
|
|
|
|
## Configuring the Project to use the Box
|
|
|
|
Now that the lucid box has been successfully added to the Vagrant installation,
|
|
we need to tell our project to use it as a base. This is done through the Vagrantfile.
|
|
Open the Vagrantfile and paste the following contents into it. The functional of
|
|
the contents should be self-explanatory:
|
|
|
|
{% highlight ruby %}
|
|
Vagrant::Config.run do |config|
|
|
config.vm.box = "lucid32"
|
|
end
|
|
{% endhighlight %}
|
|
|
|
## Testing the Setup
|
|
|
|
So far, we've only specified a base. No ports have been forwarded, no custom provisioning
|
|
has been done, etc. We literally just have one line of configuration in our Vagrantfile.
|
|
But even so, we already have a fully functional virtual machine. You can see for yourself
|
|
by running `vagrant up` which will create the environment. After a few minutes, you should
|
|
have a fully running virtual machine. We haven't yet forwarded any ports and we haven't covered
|
|
SSH yet, so you'll just have to take our word that its working for now. Finally,
|
|
when you're finished verifying the virtual machine, you can destroy everything with a
|
|
`vagrant destroy`.
|
|
|
|
{% highlight bash %}
|
|
$ vagrant up
|
|
...
|
|
$ vagrant destroy
|
|
...
|
|
{% endhighlight %}
|