Merge branch 'master' of github.com:jjasghar/chef-book

part1/01-virtualbox.md

@@ -4,11 +4,11 @@ So, you've decided to take the plunge, great.
 
 First thing first is we need to get your environment set up. I chose virtualbox and vagrant as my playground and I'll start walking you through it here.
 
-Go ahead and go [here](https://www.virtualbox.org/wiki/Download) and download the relevant virtual box binary for your base OS.  It should be straight forward install, the last pkg for my OSX install was basically Next-next-next-install.  Entered my root password and there we go.
+Go ahead and go [here](https://www.virtualbox.org/wiki/Downloads) and download the relevant virtualbox binary for your base OS.  It should be straight forward install, the last pkg for my OSX install was basically Next-next-next-install.  Entered my root password and there we go.
 
-Attempt to start it virtualbox is if comes up asking to create a virtual machine, if so go ahead to the next section.
+When virtualbox starts for the first time, it may open a wizard for creating a new virtual machine.  You can dismiss the wizard since we will download a base box in the next step.
 
-Next I strongly suggest downloading something called iTerm2 if you are on OSX.  Click [here](http://www.iterm2.com/#/section/downloads) and grab the lastest stable version.
+Next, I strongly suggest downloading something called iTerm2 if you are on OSX.  Click [here](http://www.iterm2.com/#/section/downloads) and grab the lastest stable version.
 
 _NOTE_: You don't have to use this, on OSX, you can use Terminal but iTerm2 is just better in general, trust me.
 

part1/02-vagrant.md

@@ -1,6 +1,6 @@
 vagrant
 -------
-Vagrant is a great tool designed for developers to create disposable machines with quick turn a quick turn around.  Is our case we want to install the binary NOT the gem, so go [here](http://downloads.vagrantup.com/)
+Vagrant is a great tool designed for developers to create disposable machines with a quick turn around.  In our case we want to install the binary NOT the gem, so go [here](http://downloads.vagrantup.com/)
 
 After you installed it, go ahead and spin up [Terminal|iTerm2|xterm|cmd] and type `vagrant`. You should see something like the following:
 ```bash
@@ -50,20 +50,27 @@ Bringing machine 'default' up with 'virtualbox' provider...
 [default] Matching MAC address for NAT networking...
 [default] Setting the name of the VM...
 [default] Clearing any previously set forwarded ports...
-[default] Fixed port collision for 22 => 2222. Now on port 2200.
 [default] Creating shared folders metadata...
 [default] Clearing any previously set network interfaces...
 [default] Preparing network interfaces based on configuration...
 [default] Forwarding ports...
-[default] -- 22 => 2200 (adapter 1)
+[default] -- 22 => 2222 (adapter 1)
 [default] Booting VM...
 [default] Waiting for machine to boot. This may take a few minutes...
 [default] Machine booted and ready!
+[default] The guest additions on this VM do not match the installed version of
+VirtualBox! In most cases this is fine, but in rare cases it can
+cause things such as shared folders to not work properly. If you see
+shared folder errors, please update the guest additions within the
+virtual machine and reload your VM.
+
+Guest Additions Version: 4.2.0
+VirtualBox Version: 4.3
 [default] Mounting shared folders...
 [default] -- /vagrant
 ```
 
-Go ahead and `vagrant ssh` into the box and you'll see that you have a complete box that can run linux commands, basically anything. Type something like `sudo apt-get update && sudo apt-get intsall vim -y` You'll see vim being installed. Start it up with `vim test-file` and write some things in there. `wq` out of it. Go ahead and `logout` of the machine. You should see your original command prompt from your host machine now. Type `vagrant ssh` and you should see the file that you wrote out, `cat test-file`.
+Go ahead and `vagrant ssh` into the box and you'll see that you have a complete box that can run linux commands, basically anything. Type something like `sudo apt-get update && sudo apt-get install vim -y` You'll see vim being installed. Start it up with `vim test-file` and write some things in there. `wq` out of it. Go ahead and `logout` of the machine. You should see your original command prompt from your host machine now. Type `vagrant ssh` and you should see the file that you wrote out, `cat test-file`.
 As you can see you have been able to create a base box ssh into it, and change it around, log out then log back in and not loose any of your data.
 The next step is to destroy it and start over, so in the place you did your `vagrant up` type `vagrant destroy -f` this is a "Do not pass Go" type of destroy, so be careful, you have been warned.
 As you can see with the `vagrant destroy -f`:
@@ -79,8 +86,8 @@ It shuts down the machine, and blows it up. If you attempt to `vagrant ssh` it'l
 VM must be created before running this command. Run `vagrant up` first.
 [~/vagrant/lucid32] %
 ```
-Because the machine is gone. You can simply run `vagrant up` to re-create it. You'll notice that the `test-file` nor vim is there anymore, and that's expected, you blew it up didn't you?  I strongly suggest playing around with `vagrant` the [docs](http://docs.vagrantup.com/v2/) for version 2 are extremely straight forward, and you should spend the time to get comfortable with it. It'll make your chef experance so much better. 
+Because the machine is gone. You can simply run `vagrant up` to re-create it. You'll notice that the `test-file` nor vim is there anymore, and that's expected, you blew it up didn't you?  I strongly suggest playing around with `vagrant` the [docs](http://docs.vagrantup.com/v2/) for version 2 are extremely straight forward, and you should spend the time to get comfortable with it. It'll make your chef experience so much better. 
 
-Bonus round: Try to set up an apache server/nginx server and use the [port forwarding](http://docs.vagrantup.com/v2/networking/forwarded_ports.html) with vagrant and be able to hit your http://localhost:8080 and see the default page for it.
+Bonus round: Try to set up an apache/nginx server and use [port forwarding](http://docs.vagrantup.com/v2/networking/forwarded_ports.html) with vagrant to be able to hit [http://localhost:8080](http://localhost:8080) on your workstation and see its default page.
 
 Move on to [The beginning of your playground](03-vm-setup.md)

part1/03-vm-setup.md

@@ -7,7 +7,7 @@ So you have virtualbox and vagrant running; you feel more comfortable with your
 # vi: set ft=ruby :
 $script = <<SCRIPT
 apt-get update
-apt-get upgrade -y
+DEBIAN_FRONTEND=noninteractive apt-get upgrade -y
 apt-get install git-core curl build-essential zlib1g-dev libssl-dev libreadline6-dev libyaml-dev -y
 if ! [ -a /usr/local/bin/gem ]; then
   cd /tmp
@@ -22,9 +22,9 @@ if ! [ -a /usr/local/bin/gem ]; then
 fi
 echo "America/Chicago" > /etc/timezone # because this is the timezone where I live ;)
 dpkg-reconfigure -f noninteractive tzdata
-mkdir /etc/chef/
-if ! [ -a /etc/chef/client.pem ]; then
-  curl -L https://www.opscode.com/chef/install.sh | sudo bash
+mkdir -p /etc/chef/
+if ! [ -x /opt/chef/bin/chef-solo ]; then
+  curl -L https://www.opscode.com/chef/install.sh | bash
 fi
 SCRIPT
 
@@ -37,25 +37,22 @@ Vagrant::Config.run do |config|
 end
 ```
 
-As you can see it does A LOT. I build ruby as part of the provisioning, also I install chef via the omnibus (which we'll talk about in the next section). Initially I want to use the `:shell` provisioning, I dont want to muddy the waters with putting chef-solo in before you can understand everything going on already. With the [docs](http://docs.vagrantup.com/v2/) you should be able to decipher most if not all of what's going on here.
+As you can see it does A LOT. I build ruby as part of the process, and I install chef via the omnibus installer (which we'll talk about in the next section). Initially I want to use the `:shell` provisioner so I don't muddy the waters by adding chef-solo to the mix until we're more familiar with these new tools. With the [docs](http://docs.vagrantup.com/v2/) and some familiarity with bash scripting, you should be able to decipher what's going on here. Don't worry, we'll add/hack on this file as we go through this book. This is just the beginning.
 
-Don't worry, we'll add/hack on this file as we go through this book. This is just the beginning.
+You'll also notice that this provisioning script includes a couple tests to keep from repeating unnecessary steps if it has already been run.  It is important for scripts like these to be [idempotent](http://en.wikipedia.org/wiki/Idempotence), or that they "can be applied multiple times without changing the result beyond the initial application" as described on wikipedia.
 
-You should be able to put this `Vagrantfile` in a new directory, example `~/vagrant/chef-book/` and do a `vagrant up`. You should see something like this:
+Put this `Vagrantfile` in a new directory, example `~/vagrant/chef-book/` and do a `vagrant up`. We will use it in step 5. You should see something like this:
 ```bash
 [~/vagrant/chef-book] % vagrant up
 Bringing machine 'default' up with 'virtualbox' provider...
-[default] Box 'vagrant' was not found. Fetching box from specified URL for
+[default] Box 'chef-book' was not found. Fetching box from specified URL for
 the provider 'virtualbox'. Note that if the URL does not have
 a box for this provider, you should interrupt Vagrant now and add
 the box yourself. Otherwise Vagrant will attempt to download the
 full box prior to discovering this error.
 Downloading or copying the box...
 Progress:
 ```
-After it's been pulled down, you should see that the machines is `Machine booted and ready!`. You'll be able to go into the box right then and there by `vagrant ssh` or you can `vagrant provision`.
-Then you should see a lot of provisioning text. That's good. Let it run, grab some coffee, or energy drink, what ever is your fancy. I also noticed that my terminal started throwing funky looking characters.  From what I could tell it was doing what it was supposed to, but you might have to close your terminal and reopen in to `vagrant ssh` into the box. If you are truly paranoid, you can `vagrant provision` again, to make sure everything is what you expect before `vagrant ssh`.
-
-NOTE: after the initial import of the box, it'll always go through the provisioning automatically.
+After it's been pulled down, you should see vagrant report `Machine booted and ready!`. In a different terminal window, you'll be able to go into the box right then and there by changing to the same directory as the Vagrantfile and typing `vagrant ssh`. Now you should see a lot of provisioning output. That's good. Let it run, grab some coffee or energy drink, this will take 15 to 30 minutes. Vagrant will automatically attempt to provision your box after it is created for the first time, and when it is recreated after being destroyed.
 
 Move on to [omnibus vs gem](04-omnibus-install-vs-gem-install.md)

part1/04-omnibus-install-vs-gem-install.md

@@ -3,18 +3,18 @@ omnibus vs gem
 
 Before we go any farther, we should discuss the difference and choice to use [omnibus](https://github.com/opscode/omnibus-software) over the [chef](http://rubygems.org/gems/chef) gem.
 
-Omnibus is a simple binary that installs everything you need to run chef at `/opt/chef/`. It comes with a version of ruby specifically for the chef binaries and it basically works out of the box. Hell all you need to do is run:
+Omnibus is a simple binary that installs everything you need to run chef at `/opt/chef/`. It installs a version of ruby specifically for the chef binaries and is designed to work out of the box. Hell, all you need to do is run:
 ```bash
 curl -L https://www.opscode.com/chef/install.sh | sudo bash
 ```
 And you have it installed.
 
-The gem is the typical `gem install chef` installation which for most will work, but that's assuming you have ruby already installed. Omnibus dosen't require ruby,  and extremely un-intrusive, and dosen't require separate ruby installation on every box it runs.
+The gem installation procedure is the standard `gem install chef` which will work, but that's assuming you already have ruby installed. The omnibus installer will un-intrusively containerize well-tested dependencies for chef in `/opt/chef/` so you won't need to spend time installing or configuring anything further before you can start using chef to provision your systems.
 
-It can be a personal choice though, there is nothing stopping you from doing the `gem install chef`, but I strongly suggest omnibus.
+It can be a personal choice. There is nothing stopping you from doing `gem install chef`, but I strongly suggest using omnibus.
 
-If you are already a ruby leaning person, the gem install is not much of a step to get going. On the other hand, if you lean towards something like python, and don't have ruby installed at all, you can still use chef like we did with the vagrant box, with a simple curl install.
+If you are already familiar with ruby, the gem install is not an intimidating step. On the other hand, if you lean towards something like python or don't have ruby installed at all, you can still use chef like we did with the vagrant box with a simple curl install.
 
-You might have realized also that the base box that comes from vagrant already has chef and puppet installed. Yes this is true, but you never know if it's up to date or not. Hence the reinstall with the omnibus package.
+You might also have noticed that the base box already has chef and puppet installed. While this is true, you never know if they are up to date versions. A reinstall with the omnibus package should automatically supercede any existing installation.
 
 Move on to [chef-solo](../part2/05-chef-solo.md)

part2/05-chef-solo.md

@@ -1,31 +1,17 @@
 chef-solo
 ---------
 
-So we have a working _disposable_ vm with with vagrant now? Great, let's actually start playing with chef.  The first portion we're going to start with is [chef-solo](http://docs.opscode.com/chef_solo.html) which believe it or not can cover 75-85% of the use cases of chef. Keep this in mind, as you go through this book, because honestly if it fits no need to go farther.
+So we have a working _disposable_ vm with with vagrant now? Great, let's actually start playing with chef.  We're going to start with [chef-solo](http://docs.opscode.com/chef_solo.html), which believe it or not can cover 75-85% of the use cases of chef. Keep this in mind as you go through this book, because honestly if it fits then there is no need to overengineer your solutions.
 
-The first thing to do is make sure that you are running the correct version of `chef-solo`. Type these following commands in to confirm we are set up correctly.
+The first thing to do is make sure that you are running the correct version of `chef-solo`. Restart your vagrant box with `vagrant up` if you have stopped or destroyed it. Type these following commands in to confirm we are set up correctly.
 ```bash
-[~/vagrant/chef-book] % vagrant up
-Bringing machine 'default' up with 'virtualbox' provider...
-[default] Clearing any previously set forwarded ports...
-[default] Creating shared folders metadata...
-[default] Clearing any previously set network interfaces...
-[default] Preparing network interfaces based on configuration...
-[default] Forwarding ports...
-[default] -- 22 => 2222 (adapter 1)
-[default] Booting VM...
-[default] Waiting for machine to boot. This may take a few minutes...
-[default] Machine booted and ready!
-[default] Setting hostname...
-[default] Mounting shared folders...
-[default] -- /vagrant
 14:51:58 [~/vagrant/chef-book] % vagrant ssh
 Welcome to Ubuntu 12.04 LTS (GNU/Linux 3.2.0-23-generic x86_64)
 
  * Documentation:  https://help.ubuntu.com/
 Welcome to your Vagrant-built virtual machine.
 Last login: Mon Oct 21 13:49:19 2013 from 10.0.2.2
-vagrant@chef-book:~$ sudo su -
+vagrant@chef-book:~$ sudo -i
 root@chef-book:~# which chef-solo
 /usr/bin/chef-solo
 root@chef-book:~# ls -l /usr/bin/chef-solo
@@ -50,11 +36,11 @@ Chef Client failed. 0 resources updated
 [2013-10-21T14:53:45-05:00] FATAL: Chef::Exceptions::ChildConvergeError: Chef run process exited unsuccessfully (exit code 1)
 root@chef-book:~#
 ```
-Yep, it ain't happy. Thats cool, that's expected, I just wanted to make sure you saw it in error state before taking a stab at it.
+Yep, it ain't happy. That's expected at this stage. I just wanted to make sure you saw it in error state before taking a stab at it.
 
-Ok, so we can run a `chef-solo` process/run, now lets actually talk about `chef-solo`. In the simplest terms `chef-solo` is a local provisioning software that runs through some predetermined configuration decisions, and spits out the machine how you say it should. `chef-solo`, nay all of chef, uses a compiled top down set of instuctions, or _recipes_, to build the machine how you want it to be. As you can see with the `Compiling Cookbooks...` line.
+OK, so we can start a `chef-solo` process/run, now lets actually talk about `chef-solo`. In the simplest terms, `chef-solo` is local provisioning software that runs through some preset configuration operations, and renders out the machine into the state they describe. `chef-solo`, nay all of chef, uses a compiled top down set of instuctions, or _recipes_, to build the machine how you want it to be. You can see that this process starts with the `Compiling Cookbooks...` line.
 
-In a more elegant quote from the [docs](http://docs.opscode.com/chef_solo.html) on the opscode side:
+In a more elegant quote from the [docs](http://docs.opscode.com/chef_solo.html) on the opscode site:
 > chef-solo is an open source version of the chef-client that allows using cookbooks with nodes without requiring access to a server. chef-solo runs locally and requires that a cookbook (and any of its dependencies) be on the same physical disk as the node.
 
 Now let's go on to actually running it successfully!