diff --git a/docs/getting-started/packaging.md b/docs/getting-started/packaging.md index e001b5eae..0c08ad889 100644 --- a/docs/getting-started/packaging.md +++ b/docs/getting-started/packaging.md @@ -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 %} -
-

What's with the MAC address?

-

- When an OS is installed, it typically sets up the MAC address associated - with the eth0 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 eth0. 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. -

-
- ## 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. \ No newline at end of file +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.