Updated getting started packaging guide to use new style

This commit is contained in:
Mitchell Hashimoto 2010-04-12 14:36:34 -07:00
parent 2fb223cb24
commit ddf1465c24
1 changed files with 20 additions and 32 deletions

View File

@ -15,45 +15,29 @@ containing the exported virtual machine and optionally
additional files specified on the command line. A common file also included
with boxes is a Vagrantfile. If a Vagrantfile exists in a box, it will be
added to the configuration load chain. Boxes can use a Vagrantfile to specify
default forwarded ports, SSH information, etc.
default forwarded ports, SSH information, etc. Note, however, that a Vagrantfile
is not required to be packaged with a box, and boxes will work just fine
without one.
Before working through the rest of this page, make sure the virtual environment
is built by running `vagrant up`.
## Creating the Vagrantfile
The first step is to create a Vagrantfile which does most of the heavy
lifting for the users of your box and to remove code which isn't useful
for boxes. First, backup your old Vagrantfile by copying it to something like
`Vagrantfile.bak`. Then, remove everything pertaining to provisioning, since the
packaged box will already be fully provisioned since its an export of the
running virtual machine. Second, remove the base box configuration, since
there is no base box for a box. And finally, we need to add in the MAC address of the
virtual machine so the internet access will work on any machine (more on
this later). The resulting Vagrantfile should look like the following:
First, we're going to create a basic Vagrantfile we'll package with the
box which will forward the web port. This way, users of the box can simply
add the box, do a `vagrant up`, and have everything working, including HTTP!
First, backup your old Vagrantfile by copying it to something like
`Vagrantfile.bak`. Then, create a new Vagrantfile which simply forwards the
web port. The resulting Vagrantfile should look like the following:
{% highlight ruby %}
Vagrant::Config.run do |config|
# Mac address (make sure this matches _exactly_)
config.vm.base_mac = "0800279C2E41"
# Forward apache
config.vm.forward_port("web", 80, 8080)
end
{% endhighlight %}
<div class="info">
<h3>What's with the MAC address?</h3>
<p>
When an OS is installed, it typically sets up the MAC address associated
with the <code>eth0</code> network interface, which allows the VM to connect to the
internet. But when importing a base, VirtualBox changes the MAC address
to something new, which breaks <code>eth0</code>. The MAC address of the base must
be persisted in the box Vagrantfile so that Vagrant can setup the MAC address
to ensure internet connectivity.
</p>
</div>
## Packaging the Project
Run the following code to package the environment up:
@ -71,7 +55,7 @@ The second command is where the meat is. `vagrant package` takes the virtual
environment from the current project and packages it into a `package.box`
file in the same directory. The additional options passed to the command tell
it to include the newly created Vagrantfile with it, so that the users of
the box will already have the MAC address and port forwarding setup.
the box will already have port forwarding setup.
## Distributing the Box
@ -83,14 +67,18 @@ keep the box on a secure filesystem where the public cannot access it.
If the box you're distributing is meant to be public, HTTP is the best
resource to upload to, so that anyone can easily download it.
Once the box is in place, other developers can add it like any other box:
Once the box is in place, other developers can add it and use it just
like any other box. The example below is from the point of view of a new
developer on your team using your newly packaged box:
{% highlight bash %}
$ vagrant box add my_box /path/to/the/package.box
$ vagrant init my_box
$ vagrant up
{% endhighlight %}
After that they just have to configure their Vagrantfile to use the box as
a base, run `vagrant up`, and they should have a fully working development
environment! Notice that they don't have to do provisioning or any of that;
since we already did all that, the exported virtual machine has it done
already.
At this point, they should have a fully functional environment which exactly
mirrors the environment set up in previous steps of the guide. Notice that
they didn't have to do do provisioning, or set up anything on their system
(other than Vagrant), etc. Distributing development environments has never
been so easy.