Updated getting started guide, requires 0.5.1 but working again.

docs/getting-started/boxes.md

@@ -4,41 +4,41 @@ title: Getting Started - Boxes
 ---
 # Boxes
 
-After project initialization, the next step is always to setup the
+After project initialization, the first step is always to specify the
-_base box_. Vagrant doesn't create a virtual machine _completely_ from
+_base box_ in the Vagrantfile. Vagrant doesn't create a virtual machine
-scratch. Instead, it imports a base VM, and builds off of that. This
+instance _completely_ from scratch. Instead, it imports a base image for
-simplifies things greatly for both the Vagrant developers and for the
+a VM and builds off of that. This simplifes things greatly for Vagrant
-Vagrant users, since they don't have to spend time specifying tedious
+users since they don't have to spend time specifying tedious details
-details such as memory size, hard disk size, network controllers, etc.
+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 the Getting Started Box
+## Getting a Base Box
 
-We've already packaged a basic box which contains Apache2, Passenger,
+We've already packaged a base box which has a bare bones installation
-and SQLite. While provisioning will be covered in the getting started
+of Ubuntu Lucid (10.04) 32-bit. Note that if you already downloaded
-guide, we didn't want to burden you with downloading all the cookbooks
+this box from the [overview page](/docs/getting-started/index.html) you
-for all the servers, so we'll instead cover a more simple case, although
+do not have to download it again.
-the rails box was created completely with Vagrant provisioning.
 
 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 getting_started http://files.vagrantup.com/getting_started.box
+$ 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
+Installed boxes reside in `~/.vagrant/boxes`, and they are global to the current vagrant
-installation. This means that once the rails box has been added, it can be used by
+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 "getting_started." This name
+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
@@ -49,26 +49,28 @@ the filename and logical name are equal in this case.
 Just as easily as they're added, boxes can be removed as well. The following
 is an example command to remove a box.
 
-**Do not run this command if you're following the guide. It is just an example.**
-
 {% 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 rails box has been successfully added to the Vagrant system, we need
+Now that the lucid box has been successfully added to the Vagrant installation,
-to tell our project to use it as a base. This is done through the Vagrantfile.
+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 function of the
+Open the Vagrantfile and paste the following contents into it. The functional of
-contents should be self-explanatory:
+the contents should be self-explanatory:
 
 {% highlight ruby %}
 Vagrant::Config.run do |config|
-  config.vm.box = "getting_started"
+  config.vm.box = "lucid32"
 end
 {% endhighlight %}
 

docs/getting-started/index.md

@@ -60,8 +60,8 @@ $ gem install vagrant
 ## Your First Vagrant Virtual Environment
 
 {% highlight bash %}
-$ vagrant box add base http://files.vagrantup.com/base.box
+$ vagrant box add lucid32 http://files.vagrantup.com/lucid32.box
-$ vagrant init
+$ vagrant init lucid32
 $ vagrant up
 {% endhighlight %}
 
@@ -70,5 +70,5 @@ build a fully functional virtual machine to serve rails applications, you
 should get used to the above snippet of code. After the initial setup of
 any Vagrant environment, the above is all any developer will need to create
 their development environment! Note that the above snippet does actually
-create a fully functional 360MB virtual machine running Ubuntu in the
+create a fully functional 512MB virtual machine running Ubuntu in the
 background, although the machine doesn't do much in this state.

docs/getting-started/introduction.md

@@ -14,7 +14,7 @@ Once Vagrant is installed, it is typically controlled through the `vagrant`
 command line interface. The `vagrant` binary has many "subcommands" which can be
 invoked which handle all the functionality within Vagrant, such as `vagrant up`,
 `vagrant ssh`, and `vagrant package`, to name a few. To discover all the supported
-subcommands, just run `vagrant` alone, and it'll list them out for you:
+subcommands, just run `vagrant` alone, and it'll list them out for you.
 
 ## The Vagrantfile
 
@@ -32,4 +32,4 @@ end
 
 As you can see, a Vagrantfile is simply Ruby code which typically contains a Vagrant
 configuration block. For most commands, Vagrant will first load the project's
-Vagrantfile for configuration.
+Vagrantfile for configuration.

docs/getting-started/packaging.md

@@ -10,14 +10,10 @@ you want to share the same virtual environment with them. Let's package this
 new environment into a box for them so they can get up and running
 with just a few keystrokes.
 
-Packages are tar files ending in the suffix 'box' (hence known as box files)
+Packages are exported images of your current virtual environment which
-containing the exported virtual machine and optionally
+can be easily distributed. They're typically suffixed with a "box" extension,
-additional files specified on the command line. A common file also included
+hence they are known as box files. Optionally, Vagrantfiles can be included
-with boxes is a Vagrantfile. If a Vagrantfile exists in a box, it will be
+with boxes, which can be used to specify forwarded ports, shared folders, etc.
-added to the configuration load chain. Boxes can use a Vagrantfile to specify
-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`.
@@ -43,19 +39,13 @@ end
 Run the following code to package the environment up:
 
 {% highlight bash %}
-$ vagrant halt
 $ vagrant package --include Vagrantfile
 {% endhighlight %}
 
-The first command simply halts the running virtual machine (if its running).
+`vagrant package` takes the virtual environment from the current project
-This is basically equivalent to pulling the plug on our machine and is not
+and packages it into a `package.box` file in the same directory. The additional
-recommended in general. In this case, it shouldn't really cause any damage.
+options tell it to include the newly created Vagrantfile with it, so that
-
+users of the box will already have port forwarding setup.
-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 port forwarding setup.
 
 ## Distributing the Box
 

docs/getting-started/ports.md

@@ -4,17 +4,18 @@ title: Getting Started - Port Forwarding
 ---
 # Port Forwarding
 
-So we now have this virtual environment running all these servers
+At this point we have a virtual environment running with Apache serving
-and processes. Great! But what's the use if we can't access them from
+the basic web project. But so far we can only access it from within the
-our _outside_ of the virtual environment? Well, it turns out Vagrant has
+VM, using the command line. Vagrant's goal is to provide the benefit of
-a built-in feature to handle just that: port forwarding.
+a virtualized environment without getting in your way. In order to access
+your project, Vagrant has a feature known as port forwarding.
 
-Port forwarding allows you to specify ports on the host machine to forward
+Port forwarding allows you to specify ports on the guest machine to forward
-to the guest machine. This allows you to access your web services using
+to the host machine. This enables you to access your web services using
 your own browser on your machine while the server actually sits and runs
 within a virtual machine.
 
-## Creating a Forwarded Port
+## Specifying a Forwarded Port
 
 In our case, we just want to forward Apache. Port forwarding is specified
 in the Vagrantfile, like so:
@@ -44,9 +45,11 @@ won't pick up on the forwarded ports until it is completely restarted.
 
 ## Results!
 
-At this point, after running `vagrant up`, you should be able to take your
+After running `vagrant up`, you should be able to take your
-regular old browser to `localhost:4567` and see the following page. Sure,
+regular old browser to `localhost:4567` and see the index page we created
-it's an error page, but it means that rails is running and everything is
+earlier. At this point, we have a fully functional VM ready for development for
-working!
+a basic HTML website. It should be clear to see that if PHP, Rails, etc.
+were setup, you could be developing those technologies as well.
 
-![Success!](/images/getting-started/success.jpg)
+For fun, you can also edit the `index.html` file, save it, refresh your
+browser, and immediately see your changes served directly from your VM.

docs/getting-started/provisioning.md

@@ -6,111 +6,49 @@ title: Getting Started - Provisioning
 
 Boxes aren't always going to be one-step setups for your Vagrant environment.
 Often times boxes will be used as a base for a more complicated setup. For
-example: Perhaps you're creating a rails application which also uses AMQP and
+example: Perhaps you're creating a web application which also uses AMQP and
 some custom background worker daemons. In this situation, it would be easiest
-to use the rails box, but then add the custom software on top of it (and
+to use the base box, but then add the custom software on top of it (and then
-perhaps even packaging it later so others can make use of it).
+packaging it so others can more easily make use of it, but we'll cover this
+later).
 
 Luckily, Vagrant comes with provisioning built right into the software by
 using [chef](http://www.opscode.com/chef), with support for both [chef solo](http://wiki.opscode.com/display/chef/Chef+Solo)
 and [chef server](http://wiki.opscode.com/display/chef/Chef+Server). You can
 also [extend vagrant](/docs/provisioners/others.html) to support more provisioners, but this is an advanced topic
-which we won't be covered here.
+which we won't cover here.
 
-For our basic rails app, we're going to use provisioning for a different
+For our basic HTML website, we're going to use chef provisioning to setup Apache
-purpose: installing some basic system monitoring tools, specifically [htop](http://htop.sourceforge.net/).
+to serve the website.
-The getting started guide doesn't cover more advanced cookbooks for the purpose of keeping things
-simple, but anything is possible with chef.
 
-## Creating the `htop` Cookbook
+## Configuring Chef and the Vagrant
 
-First things first, we're going to create a directory to store our cookbooks
+Since a tutorial on how to use Chef is out of scope for this getting started
-and then we're going to create the directories for the `htop` cookbook.
+guide, I've prepackaged the cookbooks for you for provisioning. You just have
-
+to configure your Vagrantfile to point to them:
-{% highlight bash %}
-$ mkdir -p cookbooks/htop/recipes
-{% endhighlight %}
-
-**Note:** Generally, cookbooks are created with Rake commands using the Rakefile
-provided by the Opscode cookbooks repository. Since what we're doing here is so
-simple, we're not using this, but most projects typically do.
-
-In the recipes directory of the `htop` cookbook, create a file named `default.rb`
-with the following contents. This file defines how chef installs `htop`. The file
-should be at `cookbooks/htop/recipes/default.rb`.
-
-{% highlight ruby %}
-# Install the htop package via the packaging system
-package "htop"
-{% endhighlight %}
-
-## Creating the `vagrant_main` Cookbook
-
-Vagrant uses `vagrant_main` as the entry-point cookbook for chef. This is
-analogous to a C program calling `int main` to start a program. The actual
-contents of the `vagrant_main` recipe should be to simply include other recipes
-in the order you want them ran. First, we'll setup the directory for this cookbook:
-
-{% highlight bash %}
-$ mkdir -p cookbooks/vagrant_main/recipes
-{% endhighlight %}
-
-And then the contents of the `default.rb` file:
-
-{% highlight ruby %}
-# Just install htop
-require_recipe "htop"
-{% endhighlight %}
-
-**Note:** The fact that Vagrant calls `vagrant_main` as the main cookbook is
-configurable using the Vagrantfile, but we won't modify it in this getting
-started guide.
-
-## Enabling Provisioning
-
-With everything is now in place, the final step is to modify the Vagrantfile
-to point to our cookbooks directory and to enable provisioning. Add the
-following contents to the project's Vagrantfile:
 
 {% highlight ruby %}
 Vagrant::Config.run do |config|
+  config.vm.box = "lucid32"
+
   # Enable the chef solo provisioner
   config.vm.provisioner = :chef_solo
 
-  # This directory is expanded relative to the project directory.
+  # Grab the cookbooks from the Vagrant files
-  config.chef.cookbooks_path = "cookbooks"
+  config.chef.recipe_url = "http://files.vagrantup.com/getting_started/cookbooks.tar.gz"
 end
 {% endhighlight %}
 
-**Note:** If you're feeling lazy, you can simply copy and paste the above code
+Note that while we use a URL to download the cookbooks for this getting
-at the end of the Vagrantfile after the previous configuration block. Vagrant
+started project, you can also put cookbooks in a local directory, which is
-runs all configuration blocks, overwriting the newest values over the older
+nice for storing your cookbooks in version control with your project. More
-values. Otherwise, you may simply copy the block contents and append it to the
+details on this can be found in the [chef solo documentation](/docs/provisioners/chef_solo.html).
-block contents of your current Vagrantfile. Either way, things will work.
 
 ## Running it!
 
-With everything setup, you can now test what we have so far. If you haven't yet
+With provisioning configured, just run `vagrant up` to create your environment
-created the vagrant environment, run `vagrant up` to create it from scratch.
+and Vagrant will automatically provision it. If your environment is already
-Otherwise, if you already ran `vagrant up` and chose to suspend or shut down
+running since you did an `up` in a previous step, just run `vagrant reload`,
-the environment during the last step, or even if its still running,
+which will quickly restart your VM, skipping the import step.
-run `vagrant reload` to simply reload the environment, but not
-create a new one.
 
-If you have no idea what's going on, run a `vagrant down` to
+TODO: create cookbooks and show output here
-tear down any potentially created vagrant environment, and start over with
-a fresh `vagrant up`.
-
-You should notice that provisioning is now part of the steps executed, and
-Vagrant will even log and output the output of chef, so you can debug any
-problems which may occur.
-
-You can verify everything worked successfully by SSHing in to the running
-environment and trying to execute `htop`:
-
-{% highlight bash %}
-$ vagrant ssh
-...
-vagrant-instance ~$ which htop
-/usr/bin/htop
-{% endhighlight %}

docs/getting-started/rebuild.md

@@ -4,13 +4,12 @@ title: Getting Started - Rebuild Instantly
 ---
 # Rebuild Instantly
 
-Let's assume its time to work on that rails project again. Maybe
+Let's assume its time to work on that web project again. Maybe
 its the next day at work, maybe its the next _year_ at work, but
-your boss wants you to work on that rails project again. Worried
+your boss wants you to work on that web project again. Worried
-about dependencies? Rails versions mismatched maybe? Server versions
+about dependencies? Software versions mismatched maybe?
-changed?
 
-Don't worry! We built the development environment for the rails
+Don't worry! We already built the development environment for the web
 project with Vagrant! Rebuilding is a snap.
 
 **Note:** If you're following along and haven't already completely
@@ -18,7 +17,7 @@ destroyed your virtual environment, please do so by running
 `vagrant down` so you can really experience this step of the
 getting started guide.
 
-Are you ready for this? Go back to that rails project directory
+Are you ready for this? Go back to that web project directory
 and issue the following command:
 
 {% highlight bash %}
@@ -28,4 +27,4 @@ $ vagrant up
 **That's _it_!** Really! In about 5 minutes or so after Vagrant
 completes setting up your environment, it should be exactly as
 you remembered it: same server layout, same dependency versions,
-no extraneous software, etc.
+no extraneous software, etc.

docs/getting-started/setup.md

@@ -27,19 +27,26 @@ $ vagrant init
 as-is, but it will be used extensively in future steps to configure our virtual
 machine.
 
-## Rails Project Setup
+## Web Project Setup
 
-With Vagrant now ready for the given directory, lets add rails to it. In the
+With Vagrant now ready for the given directory, let's create a quick "web project"
-same directory run the `rails` command:
+which we'll use later to showcase your VM. Run the following command in your
+project directory (the directory with the Vagrantfile):
 
 {% highlight bash %}
-$ rails .
+$ echo "<h1>Hello from a Vagrant VM!</h1>" > index.html
-$ rm public/index.html
 {% endhighlight %}
 
-This creates a rails-app in the current directory. It also removes the static
+The above steps could have been run in any order. Vagrant can easily be initialized
-index file but leaves everything else as-is. This guide is assuming you're
+in pre-existing project folders.
-using **Rails 2.3.5**.
 
-The above setups required (rails and vagrant) could have been run in any order.
+<div class="info">
-Vagrant can easily be initialized in already-existing project folders.
+  <h3>What about PHP? Python? Java?</h3>
+  <p>
+    To keep this getting started guide simple and as general as possible,
+    uses an HTML-based project as an example, but Vagrant doesn't make
+    any assumptions about the type of project you're developing. It should
+    be clear after going through the getting started guide on how to use Vagrant
+    with other types of web projects.
+  </p>
+</div>

docs/getting-started/setup/ubuntu.md

@@ -25,9 +25,9 @@ fairly painless:
 
 {% highlight bash %}
 $ cd ~
-$ wget http://rubyforge.org/frs/download.php/69365/rubygems-1.3.6.tgz
+$ wget http://production.cf.rubygems.org/rubygems/rubygems-1.3.7.tgz
-$ tar xvzf rubygems-1.3.6.tgz
+$ tar xvzf rubygems-1.3.7.tgz
-$ cd rubygems-1.3.6
+$ cd rubygems-1.3.7
 $ sudo ruby setup.rb
 $ sudo ln -s /usr/bin/gem1.8 /usr/bin/gem
 {% endhighlight bash %}

docs/getting-started/ssh.md

@@ -6,7 +6,7 @@ title: Getting Started - SSH
 
 Even though Vagrant allows for a vast amount of configuration through its
 commands and the Vagrantfile, nothing beats the power of the command line.
-Some times you just have to get into the files and play around to get things
+Sometimes you just have to get into the files and play around to get things
 working just right or to debug an application.
 
 Vagrant provides full SSH access to the virtual environments it creates
@@ -15,6 +15,9 @@ will automatically drop you into a fully functional terminal shell (it
 really is just `ssh`  being run, there is no middle man involved in communicating
 from the VM to the host machine).
 
+After running `vagrant ssh`, you should see something similar to the
+following:
+
 {% highlight bash %}
 $ vagrant ssh
 ...
@@ -40,35 +43,15 @@ vagrant@vagrantbase:~$
 
 Vagrant bridges your application with the virtual environment by using a
 VirtualBox shared folder. The shared folder location on the virtual machine
-is specified with the `config.vm.project_directory` setting which can be set
+is specified with the `config.vm.project_directory` in the Vagrantfile, but
-in the Vagrantfile, but it defaults to `/vagrant`. This can be verified by
+defaults to `/vagrant`. This can be verified by listing the files within
-checking the files within that folder from the SSH session.
+that folder in the SSH session:
 
 {% highlight bash %}
 vagrant@vagrantbase:~$ ls /vagrant
-app  config  db  doc  lib  log  public  Rakefile
+index.html Vagrantfile
-README  script  test  tmp  Vagrantfile  vendor
 {% endhighlight %}
 
-The VM has both read and write access to the shared folder. Remember: Any
+The VM has both read and write access to the shared folder.
-changes are mirrored across both systems.
-
-## Creating the SQLite Database
-
-Before we work on provisioning or anything else, its now important that
-we create the SQLite database for the project. Sure, this could've been
-done on the host side, but we're going to do it through SSH on the virtual
-machine to verify that rails works, at least to that extent. Be sure to
-`vagrant up` prior to doing this:
-
-{% highlight bash %}
-$ vagrant ssh
-...
-Welcome to your vagrant instance!
-Last login: Fri Mar  5 23:21:47 2010 from 10.0.2.2
-vagrant@vagrantbase:~$ cd /vagrant
-vagrant@vagrantbase:/vagrant$ sudo rake db:create
-(in /vagrant)
-vagrant@vagrantbase:~$
-{% endhighlight %}
 
+**Remember: Any changes are mirrored across both systems.**

docs/getting-started/teardown.md

@@ -5,42 +5,51 @@ title: Getting Started - Teardown
 # Teardown
 
 We now have a fully functional virtual machine which can be used
-for basic rails development. We've packaged this virtual machine up
+for basic web development. We've packaged this virtual machine up
 and we've given it to other members of our team. But now lets say its time to
 switch gears, maybe work on another project, maybe go out to lunch,
 or maybe just go home. What do we do to clean up our development
 environment?
 
+There are three options to clean up your environment:
+
+1. Suspending
+1. Halting
+1. Destroying
+
+Each of these options and their pros and cons will be covered below.
+
 ## Suspending the Environment
 
 One option is to _suspend the virtual machine_ by running `vagrant suspend`.
-This will take a snapshot of the current [VirtualBox](http://www.virtualbox.org)
+This will save the current running state of your virtual machine and then
-Vagrant has created and will stop it. To resume working again at some other
+stop it. To resume working again at some other time, simply issue a `vagrant resume`
-time, simply issue a `vagrant resume` to get going!
+to get going!
 
-#### Pros
+The main benefit of this is that resuming your work again is quick, a matter
+of maybe 10 to 15 seconds. The cost is that your disk space is still consumed
+by the virtual machine. An average virtual machine takes up about 1 GB of disk
+space.
 
-* Exact state is saved, the VM basically restarts at the last running instruction.
+## Halting the Environment
-* Fast resume since there is no need to wait for Vagrant to rebuild the entire
-  environment.
 
-#### Cons
+Another option is to _halt the virtual machine_ by running `vagrant halt`.
+This will attempt a graceful shutdown of your VM (such as issuing a `halt`
+in a linux machine) and wait for it to shut down. To resume working again,
+issue a `vagrant up`, which will reboot the machine but will not repeat
+the import sequence (since its already imported).
 
-* Disk space is still consumed by Vagrant. An average virtual machine takes
+The main benefit of this is it allows you to cleanly shut down your VM,
-  up about 500 MB of disk space. This is left on your system with a suspension.
+and allow it from a cold state again. The cost is that you still pay
+for the disk space that is consumed by the virtual machine.
 
 ## Destroying the Environment
 
-The other option is to _completely destroy the virtual environment_. This
+Finally, you can _completely destroy the virtual environment_. This can be
-can be done by running `vagrant down` which will literally delete all traces
+done by running `vagrant down` which will literally delete all traces of the
-of the virtual environment off the disk. To get started again, simply run
+virtual environment off the disk. To get started again, run `vagrant up` and
-a `vagrant up` and Vagrant will rebuild your environment.
+your environment will be rebuilt.
 
-#### Pros
+The benefit of this is that your disk space is completely restored to
-
+pre-VM state, saving you about 1 GB on average. The cost is that you must
-* No trace left of the virtual environment. No disk space is used other than
+wait for a full rebuild when you `vagrant up` again.
-  the configuration files.
-
-#### Cons
-
-* Rebuilding the VM will take a few minutes when `vagrant up` is ran.