Updating base box creation guide

* Adding helpful info bubbles, questions/answers, and tips
* Correcting/adding various bits to make the process smoother

css/screen.css

@@ -154,6 +154,24 @@ blockquote {
   font-style: normal;
 }
 
+/* -----    info boxes   -----  */
+
+.info {
+  padding-left: 52px;
+  margin-top: 0px;
+  margin-bottom: 10px;
+  border: 1px dotted #DDD;
+  background-image: url(/images/icons/error.png);
+  background-position: 10px 10px;
+  background-color: #EEEEEE;
+  background-repeat: no-repeat;
+  color: #000;
+  font-size: 0.8em;
+}
+
+  .info h3 {
+    font-size: 1.3em;
+  }
 
 /* -------------------------------
               HEADER

docs/base_boxes.md

@@ -4,30 +4,40 @@ title: Documentation - Base Boxes
 ---
 # Base Boxes
 
+<div class="info">
+  <h3>This topic is for advanced users</h3>
+  <p>
+    The following topic is for <em>advanced</em> users. The majority of Vagrant users will
+    never have to do this. Therefore, only continue if you want to have custom OS or custom
+    version setups not currently available. This guide also assumes you know how to install
+    operating systems and are familiar with various UNIX commands you'll need along the way.
+  </p>
+</div>
+
 A special category known as "base boxes" are the boxes which contain
 the bare bones necessary for Vagrant to function. The basic requirements
 of the base box are the following:
 
-* SSH with basic username/password SSH authentication
-* Password-less `sudo`
-* Ruby
-* RubyGems
-* Chef
 * VirtualBox Guest Additions for shared folders, port forwarding, etc.
+* SSH with basic username/password SSH authentication
+* Password-less `sudo` for the main account
+* Ruby & RubyGems to install Chef
+* Chef for provisioning support
 
 The above are absolutely _required_ by Vagrant to work properly with the
 base box. The versions themselves are up to you as long as everything
-(Ruby and Chef) work properly together.
+(Ruby and Chef) works properly together.
 
-**What about security?** A common question is "Why the password-less `sudo`?"
+<div class="info">
-or "What about public/private keys?" Our answer to this is that since Vagrant
+  <h3>What about security?</h3>
-targets development environments, security is not a major concern, and we
+  <p>
-currently value simplicity over it. In the future we may support keys, password
+    A common question is "Why the password-less <code>sudo</code>?"
-`sudo`, etc. but for now this is not possible with Vagrant.
+    or "What about public/private keys?". Our answer to this is that since Vagrant
-
+    targets development environments, security is not a major concern, and we
-**Note:** This topic is _advanced_ and in general most users of Vagrant will
+    currently value simplicity over it. In the future we may support keys, password
-never have to do this. This is only useful for those wishing to have custom
+    <code>sudo</code>, etc. but for now this is not possible with Vagrant.
-OS or custom version setups.
+  </p>
+</div>
 
 ## Creating Base Boxes
 
@@ -52,14 +62,46 @@ Now this is **really important**: Make sure the network controller is set to
 connects are not supported since it requires the machine to specify which
 device it is bridged to, which is unknown.
 
-For consistency across various Vagrant boxes, if you plan to distribute the box,
+Now go ahead and boot up the Virtual Machine and install the operating system.
-please follow these conventions where possible:
 
-* Hostname: vagrant-[os-name],  e.g.  vagrant-debian-lenny
+<div class="info">
-* Domain: vagrantup.com
+  <h3>Size does matter!</h3>
-* Root Password: vagrant
+  <p>
-* Main user username: vagrant
+    Having an environment you can send and have others boot up is really neat,
-* Main user password: vagrant
+    but not very portable if your file is a 5GB download. Even 1GB is pushing
+    the limits. You should aim for a final Box size of no more than 500mb. In
+    order to acehive that size, there is a few things you can do.
+  </p>
+  <ul>
+    <li>Install the operating system without a GUI. That is, when prompted,
+      deselect the option to install a desktop environment. On a Debian Lenny
+      install, the final box size difference between an OS with and without a
+      desktop environment way a whole 1GB. You'll need a good knowledge of
+      command line commands if you go this route.</li>
+    <li>Clear the system cache before you export at the end. You don't need tmp
+      files, or cache system packages. In the case of Debian or Ubuntu based OSs,
+      you can clean the cache with `apt-get clean`.</li>
+    <li>Where possible, avoid installing all the documentation. When installing
+      RubyGems for example, append `--no-rdoc --no-ri` to the install command.</li>
+  </ul>
+</div>
+
+<div class="info">
+  <h3>Convention over Configuration</h3>
+  <p>
+    Choice is a good thing, so just about everything in Vagrant can be changed.
+    However, it's easier for others to use Vagrant when you follow a set of
+    conventions. Now, while these aren't enforced conventions, if you plan to
+    distribute the box, it is recommended you follow the following where possible:
+  </p>
+  <ul>
+    <li>Hostname: vagrant-[os-name],  e.g.  vagrant-debian-lenny</li>
+    <li>Domain: vagrantup.com</li>
+    <li>Root Password: vagrant</li>
+    <li>Main account login: vagrant</li>
+    <li>Main account password: vagrant</li>
+  </ul>
+</div>
 
 ### Setup Permissions
 
@@ -67,18 +109,26 @@ Once the VM is created, boot it up. Then lets start by making sure the user has
 permissions. Specifically the main user should have **password-less `sudo` privileges**.
 We do this by running `su` and entering the root password you entered during the
 installation of the operating system. Once logged in, run `visudo` and and set the admin
-group to use no password. The line in the `visudo` configuration to do that looks like this:
+group to use no password.
+
+**Note:** Some bare bones systems will not include `sudo` by default. If `visudo` is not an
+available command, install the `sudo` package for your operating system.
+
+The line you should add in the `visudo` configuration to do that looks like this:
 
 {% highlight bash %}
 %admin ALL=NOPASSWD: ALL
 {% endhighlight %}
 
-If you unfamiliar with vi, the editor visudo uses, press 'i' to start input, ESC to stop
+If you unfamiliar with vi, the editor `visudo` uses, press 'i' to start input, ESC to stop
-input, CTRL+X to quit, and type 'Y' to save. Once that is setup, you may need to make the
+input, CTRL+X to quit, type 'Y' to save, then hit Enter/Return. Once that is setup, you
-'admin' group, and you then need to assign the main user to that group.
+may need to make the 'admin' group, and you then need to assign the main user to that group
+(on Debian and Ubuntu systems, this is done with groupadd and usermod. Consult the documentation
+for the commands your operating system uses).
 
-Finally, verify that sudo works without a password, but running 'exit' out of the root
+Then restart sudo using `/etc/init.d/sudo restart` (command may defer on operating systems).
-account, then `sudo su sudo`. You should get output similar to '/usr/bin/sudo'.
+Finally, verify that sudo works without a password, but running `exit` out of the root
+account, then `sudo which sudo`. You should get output similar to `/usr/bin/sudo`.
 
 ### Install VirtualBox Guest Additions
 
@@ -95,9 +145,8 @@ $ sudo apt-get install linux-headers-$(uname -r) build-essential
 {% endhighlight %}
 
 Next, make sure to insert the guest additions image by using the GUI and clicking
-on "Devices" followed by "Install Guest Additions.". Now, depending on your operating
+on "Devices" followed by "Install Guest Additions.". Then run the following to
-system, the guest additions may or may not be mounted. If /cdrom doesn't exist, then
+mount the cdrom:
-run the following to mount the cdrom:
 
 {% highlight bash %}
 $ sudo mount /media/cdrom
@@ -111,25 +160,24 @@ sudo sh /cdrom/VBoxLinuxAdditions-x86.run
 {% endhighlight %}
 
 The install will probably warn you about not installing OpenGL or Window System Drivers,
-but this is okay. Once setup, shut down the VM.
+but this is okay.
 
 ### Boot and Setup Basic Software
 
-Nearly done. We need to setup the software Vagrant relies on. The
+We need to setup the software Vagrant relies on. The _required_ software is listed below:
-_required_ software is listed below:
 
 * **Ruby** - Use the dev package so mkmf is present for Chef
 * **RubyGems** - For Chef
 * **Chef** - For provisioning support.
 * **SSH**
 
-These are typically straightforward to install the details won't be gone
+These are typically straightforward to install the details won't be gone into here. If
-into here. If promoted, make sure that the SSH uses **basic username/password authentication**
+promoted, make sure that the SSH uses **basic username/password authentication** and
-and write down the username/password.
+write down the username/password.
 
 ### Copy the MAC Address
 
-When the OS installs, it typically sets up the basic network devices (eth0 and so on)
+Nearly done. When the OS installs, it typically sets up the basic network devices (eth0 and so on)
 automatically. This includes setting the MAC address of these devices. Since configuring
 these network devices is often very OS-specific, instead of Vagrant dynamically setting
 this at runtime, it forces VirtualBox to use a specific MAC address. This requires
@@ -139,6 +187,8 @@ below:
 
 ![Copying MAC Address](/images/base_box_mac.jpg)
 
+Now go ahead and shutdown the virtual machine before continuing.
+
 ### Export the Virtual Machine
 
 Next, export the virtual machine with "File" then "Export Appliance." Export it to
@@ -192,4 +242,13 @@ $ tar -cvf package.box ./*
 {% endhighlight %}
 
 The result is `package.box` which can be distributed and installed by
-Vagrant user. Don't forget to test it yourself!
+Vagrant user. Don't forget to test it yourself!
+
+<div class="info">
+  <h3>Hold on, why not .gz, .bz2, or .7z ?!</h3>
+  <p>
+    Simple. When you export the virtual machine from VirtualBox, it is
+    already compressed. Adding additional compression is slower and yields
+    no smaller box size than just using tar.
+  </p>
+</div>