From d247258e25abbdb67f9011e40d7cc3886398df16 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Mon, 26 Jul 2010 09:12:34 -0700 Subject: [PATCH 01/10] Typo correction: down => destroy --- docs/getting-started/boxes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/boxes.md b/docs/getting-started/boxes.md index 95497715b..7367b099f 100644 --- a/docs/getting-started/boxes.md +++ b/docs/getting-started/boxes.md @@ -81,11 +81,11 @@ by running `vagrant up` which will create the environment. After a few minutes, have a fully running virtual machine. We haven't yet forwarded any ports and we haven't covered SSH yet, so you'll just have to take our word that its working for now. Finally, when you're finished verifying the virtual machine, you can destroy everything with a -`vagrant down`. +`vagrant destroy`. {% highlight bash %} $ vagrant up ... -$ vagrant down +$ vagrant destroy ... {% endhighlight %} From c0c224ce1aab49d0c8bd2cc99e4d05ca14b0ffe1 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Mon, 26 Jul 2010 09:27:46 -0700 Subject: [PATCH 02/10] Add "The Future" section to changelog --- docs/changes/changes_04x_05x.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/changes/changes_04x_05x.md b/docs/changes/changes_04x_05x.md index 968f9d2c1..9d3bd5453 100644 --- a/docs/changes/changes_04x_05x.md +++ b/docs/changes/changes_04x_05x.md @@ -69,3 +69,17 @@ for future features. I expect these changes to bring about more stability in the long run to Vagrant, while possibly causing some very minor short term bugs, though my coworkers and I have been using Vagrant 0.5 in-house for a few weeks now without issue. + +## The Future + +Since this release was mostly internals, despite a couple big new features, I think it is important +that I talk a bit about my plans for the future of this project. Vagrant 0.6 will +be a _huge_ release and the features are already set for it, they just need to be +developed. More details on this will be available to the mailing list as the +features are developed. + +Besides pure Vagrant releases, an official community-powered Vagrant box listing +website has been under development and will be deployed and available shortly. + +And finally, before Vagrant 0.6, I'm going to take the time to redo the getting +started guide and updating the screencast as well. From 7e1a68e2923439e07622257b2ab630d5e4b572f6 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Fri, 30 Jul 2010 18:11:34 -0700 Subject: [PATCH 03/10] Update link to base box to use lucid32 box --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index d341e28ab..0e695fba2 100644 --- a/index.md +++ b/index.md @@ -18,7 +18,7 @@ the [getting started guide](/docs/getting-started/index.html), the {% highlight bash %} $ gem install vagrant -$ vagrant box add base http://files.vagrantup.com/base.box +$ vagrant box add base http://files.vagrantup.com/lucid32.box $ vagrant init $ vagrant up {% endhighlight %} From 58ec79144567b79b6c64774dc27b04897208fd40 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Fri, 30 Jul 2010 18:13:30 -0700 Subject: [PATCH 04/10] Remove 0.5 release announcement --- _includes/header.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_includes/header.html b/_includes/header.html index dd1209490..e233a1eab 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -34,7 +34,7 @@
-
+ From 0208c24a12d4eaf9e709ec889ee9b8e43889779d Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Sat, 31 Jul 2010 08:01:16 -0700 Subject: [PATCH 05/10] Updated getting started guide, requires 0.5.1 but working again. --- docs/getting-started/boxes.md | 48 ++++++------ docs/getting-started/index.md | 6 +- docs/getting-started/introduction.md | 4 +- docs/getting-started/packaging.md | 26 ++----- docs/getting-started/ports.md | 27 ++++--- docs/getting-started/provisioning.md | 110 ++++++--------------------- docs/getting-started/rebuild.md | 13 ++-- docs/getting-started/setup.md | 27 ++++--- docs/getting-started/setup/ubuntu.md | 6 +- docs/getting-started/ssh.md | 37 +++------ docs/getting-started/teardown.md | 55 ++++++++------ 11 files changed, 145 insertions(+), 214 deletions(-) diff --git a/docs/getting-started/boxes.md b/docs/getting-started/boxes.md index 7367b099f..a0e983059 100644 --- a/docs/getting-started/boxes.md +++ b/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 -_base box_. Vagrant doesn't create a virtual machine _completely_ from -scratch. Instead, it imports a base VM, and builds off of that. This -simplifies things greatly for both the Vagrant developers and for the -Vagrant users, since they don't have to spend time specifying tedious -details such as memory size, hard disk size, network controllers, etc. +After project initialization, the first step is always to specify the +_base box_ in the Vagrantfile. Vagrant doesn't create a virtual machine +instance _completely_ from scratch. Instead, it imports a base image for +a VM and builds off of that. This simplifes things greatly for Vagrant +users since they don't have to spend time specifying tedious details +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, -and SQLite. While provisioning will be covered in the getting started -guide, we didn't want to burden you with downloading all the cookbooks -for all the servers, so we'll instead cover a more simple case, although -the rails box was created completely with Vagrant provisioning. +We've already packaged a base box which has a bare bones installation +of Ubuntu Lucid (10.04) 32-bit. Note that if you already downloaded +this box from the [overview page](/docs/getting-started/index.html) you +do not have to download it again. 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 -installation. This means that once the rails box has been added, it can be used by +Installed boxes reside in `~/.vagrant/boxes`, and they are global to the current vagrant +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 -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 -contents should be self-explanatory: +Now that the lucid box has been successfully added to the Vagrant installation, +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 functional of +the contents should be self-explanatory: {% highlight ruby %} Vagrant::Config.run do |config| - config.vm.box = "getting_started" + config.vm.box = "lucid32" end {% endhighlight %} diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 24635b176..c59718fa0 100644 --- a/docs/getting-started/index.md +++ b/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 init +$ vagrant box add lucid32 http://files.vagrantup.com/lucid32.box +$ 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. diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index 0047e9dda..e60325f7b 100644 --- a/docs/getting-started/introduction.md +++ b/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. \ No newline at end of file +Vagrantfile for configuration. diff --git a/docs/getting-started/packaging.md b/docs/getting-started/packaging.md index 0c08ad889..0ac930ac0 100644 --- a/docs/getting-started/packaging.md +++ b/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) -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. Note, however, that a Vagrantfile -is not required to be packaged with a box, and boxes will work just fine -without one. +Packages are exported images of your current virtual environment which +can be easily distributed. They're typically suffixed with a "box" extension, +hence they are known as box files. Optionally, Vagrantfiles can be included +with boxes, which can be used to specify forwarded ports, shared folders, etc. 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). -This is basically equivalent to pulling the plug on our machine and is not -recommended in general. In this case, it shouldn't really cause any damage. - -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. +`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 tell it to include the newly created Vagrantfile with it, so that +users of the box will already have port forwarding setup. ## Distributing the Box diff --git a/docs/getting-started/ports.md b/docs/getting-started/ports.md index 6fab23a14..976f710c6 100644 --- a/docs/getting-started/ports.md +++ b/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 -and processes. Great! But what's the use if we can't access them from -our _outside_ of the virtual environment? Well, it turns out Vagrant has -a built-in feature to handle just that: port forwarding. +At this point we have a virtual environment running with Apache serving +the basic web project. But so far we can only access it from within the +VM, using the command line. Vagrant's goal is to provide the benefit of +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 -to the guest machine. This allows you to access your web services using +Port forwarding allows you to specify ports on the guest machine to forward +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 -regular old browser to `localhost:4567` and see the following page. Sure, -it's an error page, but it means that rails is running and everything is -working! +After running `vagrant up`, you should be able to take your +regular old browser to `localhost:4567` and see the index page we created +earlier. At this point, we have a fully functional VM ready for development for +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) \ No newline at end of file +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. diff --git a/docs/getting-started/provisioning.md b/docs/getting-started/provisioning.md index 0b7cb3c15..5b119891f 100644 --- a/docs/getting-started/provisioning.md +++ b/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 -perhaps even packaging it later so others can make use of it). +to use the base box, but then add the custom software on top of it (and then +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 -purpose: installing some basic system monitoring tools, specifically [htop](http://htop.sourceforge.net/). -The getting started guide doesn't cover more advanced cookbooks for the purpose of keeping things -simple, but anything is possible with chef. +For our basic HTML website, we're going to use chef provisioning to setup Apache +to serve the website. -## Creating the `htop` Cookbook +## Configuring Chef and the Vagrant -First things first, we're going to create a directory to store our cookbooks -and then we're going to create the directories for the `htop` cookbook. - -{% 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: +Since a tutorial on how to use Chef is out of scope for this getting started +guide, I've prepackaged the cookbooks for you for provisioning. You just have +to configure your Vagrantfile to point to them: {% 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. - config.chef.cookbooks_path = "cookbooks" + # Grab the cookbooks from the Vagrant files + 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 -at the end of the Vagrantfile after the previous configuration block. Vagrant -runs all configuration blocks, overwriting the newest values over the older -values. Otherwise, you may simply copy the block contents and append it to the -block contents of your current Vagrantfile. Either way, things will work. +Note that while we use a URL to download the cookbooks for this getting +started project, you can also put cookbooks in a local directory, which is +nice for storing your cookbooks in version control with your project. More +details on this can be found in the [chef solo documentation](/docs/provisioners/chef_solo.html). ## Running it! -With everything setup, you can now test what we have so far. If you haven't yet -created the vagrant environment, run `vagrant up` to create it from scratch. -Otherwise, if you already ran `vagrant up` and chose to suspend or shut down -the environment during the last step, or even if its still running, -run `vagrant reload` to simply reload the environment, but not -create a new one. +With provisioning configured, just run `vagrant up` to create your environment +and Vagrant will automatically provision it. If your environment is already +running since you did an `up` in a previous step, just run `vagrant reload`, +which will quickly restart your VM, skipping the import step. -If you have no idea what's going on, run a `vagrant down` to -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 %} \ No newline at end of file +TODO: create cookbooks and show output here diff --git a/docs/getting-started/rebuild.md b/docs/getting-started/rebuild.md index 8024b78a2..e45d46283 100644 --- a/docs/getting-started/rebuild.md +++ b/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 -about dependencies? Rails versions mismatched maybe? Server versions -changed? +your boss wants you to work on that web project again. Worried +about dependencies? Software versions mismatched maybe? -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 newline at end of file +no extraneous software, etc. diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 44244bd5f..0edf66cbf 100644 --- a/docs/getting-started/setup.md +++ b/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 -same directory run the `rails` command: +With Vagrant now ready for the given directory, let's create a quick "web project" +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 . -$ rm public/index.html +$ echo "

Hello from a Vagrant VM!

" > index.html {% endhighlight %} -This creates a rails-app in the current directory. It also removes the static -index file but leaves everything else as-is. This guide is assuming you're -using **Rails 2.3.5**. +The above steps could have been run in any order. Vagrant can easily be initialized +in pre-existing project folders. -The above setups required (rails and vagrant) could have been run in any order. -Vagrant can easily be initialized in already-existing project folders. \ No newline at end of file +
+

What about PHP? Python? Java?

+

+ 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. +

+
diff --git a/docs/getting-started/setup/ubuntu.md b/docs/getting-started/setup/ubuntu.md index bd0646550..7f0343845 100644 --- a/docs/getting-started/setup/ubuntu.md +++ b/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 -$ tar xvzf rubygems-1.3.6.tgz -$ cd rubygems-1.3.6 +$ wget http://production.cf.rubygems.org/rubygems/rubygems-1.3.7.tgz +$ tar xvzf rubygems-1.3.7.tgz +$ cd rubygems-1.3.7 $ sudo ruby setup.rb $ sudo ln -s /usr/bin/gem1.8 /usr/bin/gem {% endhighlight bash %} diff --git a/docs/getting-started/ssh.md b/docs/getting-started/ssh.md index 70b1f4f0c..01f5e170d 100644 --- a/docs/getting-started/ssh.md +++ b/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 -in the Vagrantfile, but it defaults to `/vagrant`. This can be verified by -checking the files within that folder from the SSH session. +is specified with the `config.vm.project_directory` in the Vagrantfile, but +defaults to `/vagrant`. This can be verified by listing the files within +that folder in the SSH session: {% highlight bash %} vagrant@vagrantbase:~$ ls /vagrant -app config db doc lib log public Rakefile -README script test tmp Vagrantfile vendor +index.html Vagrantfile {% endhighlight %} -The VM has both read and write access to the shared folder. Remember: Any -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 %} +The VM has both read and write access to the shared folder. +**Remember: Any changes are mirrored across both systems.** diff --git a/docs/getting-started/teardown.md b/docs/getting-started/teardown.md index 220c7a41c..1bd637436 100644 --- a/docs/getting-started/teardown.md +++ b/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) -Vagrant has created and will stop it. To resume working again at some other -time, simply issue a `vagrant resume` to get going! +This will save the current running state of your virtual machine and then +stop it. To resume working again at some other time, simply issue a `vagrant resume` +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. -* Fast resume since there is no need to wait for Vagrant to rebuild the entire - environment. +## Halting the 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 - up about 500 MB of disk space. This is left on your system with a suspension. +The main benefit of this is it allows you to cleanly shut down your VM, +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 -can be done by running `vagrant down` which will literally delete all traces -of the virtual environment off the disk. To get started again, simply run -a `vagrant up` and Vagrant will rebuild your environment. +Finally, you can _completely destroy the virtual environment_. This can be +done by running `vagrant down` which will literally delete all traces of the +virtual environment off the disk. To get started again, run `vagrant up` and +your environment will be rebuilt. -#### Pros - -* No trace left of the virtual environment. No disk space is used other than - the configuration files. - -#### Cons - -* Rebuilding the VM will take a few minutes when `vagrant up` is ran. +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 +wait for a full rebuild when you `vagrant up` again. From 57ff845843f865dc23c31dbb32ce606150fe3891 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Sat, 31 Jul 2010 08:29:49 -0700 Subject: [PATCH 06/10] Update getting started guide with fixes and complete output examples --- docs/getting-started/provisioning.md | 16 +++++++++++++++- docs/getting-started/setup.md | 2 +- docs/getting-started/ssh.md | 4 +--- 3 files changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/getting-started/provisioning.md b/docs/getting-started/provisioning.md index 5b119891f..0f59fc851 100644 --- a/docs/getting-started/provisioning.md +++ b/docs/getting-started/provisioning.md @@ -51,4 +51,18 @@ and Vagrant will automatically provision it. If your environment is already running since you did an `up` in a previous step, just run `vagrant reload`, which will quickly restart your VM, skipping the import step. -TODO: create cookbooks and show output here +After Vagrant completes running, the web server will be up and running as well. +You can't see your website from your own browser yet, since we haven't covered +port forwarding, but you can verify that the provisioning works by SSHing into +the VM and checking the output of hitting `127.0.0.1`: + +{% highlight bash %} +$ vagrant ssh +... +vagrant@vagrantup:~$ wget -qO- 127.0.0.1 +

Hello from a Vagrant VM

+vagrant@vagrantup:~$ +{% endhighlight %} + +In the next step of the getting started guide, we'll show you how to view +your website using your own browser. diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 0edf66cbf..85c090726 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -34,7 +34,7 @@ which we'll use later to showcase your VM. Run the following command in your project directory (the directory with the Vagrantfile): {% highlight bash %} -$ echo "

Hello from a Vagrant VM!

" > index.html +$ echo "

Hello from a Vagrant VM

" > index.html {% endhighlight %} The above steps could have been run in any order. Vagrant can easily be initialized diff --git a/docs/getting-started/ssh.md b/docs/getting-started/ssh.md index 01f5e170d..9540ace49 100644 --- a/docs/getting-started/ssh.md +++ b/docs/getting-started/ssh.md @@ -21,9 +21,7 @@ following: {% 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:~$ +vagrant@vagrantup:~$ {% endhighlight %}
From 7b376ca9aba65186d7f06e24e6062b2e8a864b49 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Sat, 31 Jul 2010 08:40:26 -0700 Subject: [PATCH 07/10] Remove references to base.box, since it is no more --- docs/boxes.md | 10 +++++----- docs/converting_password_to_key_ssh.md | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/boxes.md b/docs/boxes.md index 7c5425823..66c2ccdc7 100644 --- a/docs/boxes.md +++ b/docs/boxes.md @@ -19,11 +19,11 @@ Boxes are also required as a base for all vagrant projects. The Boxes can be installed from the filesystem or via HTTP (note that if you're interested, its quite easy to extend this to support more protocols). No matter the source, the installation method is the same. -The following adds a box named `ubuntu_base` to a local vagrant +The following adds a box named `lucid32` to a local vagrant installation: {% highlight bash %} -$ vagrant box add ubuntu_base http://files.vagrantup.com/base.box +$ vagrant box add lucid32 http://files.vagrantup.com/lucid32.box {% endhighlight %} The name used with the `vagrant box add` command is the name used to @@ -38,11 +38,11 @@ first few commands tell you to add a box named "base" to the project. ## Removing a Box Boxes can just as easily be removed using the same `vagrant box` command. -The following command removes the `ubuntu_base` box which was added in the +The following command removes the `lucid32` box which was added in the previous section: {% highlight bash %} -$ vagrant box remove ubuntu_base +$ vagrant box remove lucid32 {% endhighlight %} **Warning:** There is no going back from this command. This command literally @@ -58,7 +58,7 @@ $ vagrant box list ===================================================================== Installed Vagrant Boxes: -base +lucid32 ===================================================================== {% endhighlight %} diff --git a/docs/converting_password_to_key_ssh.md b/docs/converting_password_to_key_ssh.md index 1d06d3480..7248b6016 100644 --- a/docs/converting_password_to_key_ssh.md +++ b/docs/converting_password_to_key_ssh.md @@ -14,7 +14,7 @@ key-based SSH.

We updated our boxes!

If you're not using a custom base box, and you're using one of the base - boxes we created (getting_started.box, base.box, etc.), + boxes we created (lucid32.box, lucid64.box, etc.) then just remove your old box and download the new one. We updated all of our boxes to work with 0.2.x!

@@ -85,4 +85,4 @@ $ vagrant package --include Vagrantfile This should spit out a `package.box` file in the current working directory which you can now re-add to your system and use. It should be a drop-in replacement for -your previously broken box. \ No newline at end of file +your previously broken box. From bbdf675dfe7dac6de7dab4f9d6bf8571ef807f2b Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Sat, 31 Jul 2010 11:04:06 -0700 Subject: [PATCH 08/10] Update styling and text on chef solo docs --- css/screen.css | 4 ++++ docs/provisioners/chef_solo.md | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/css/screen.css b/css/screen.css index 2913c9899..4d89546c7 100644 --- a/css/screen.css +++ b/css/screen.css @@ -313,6 +313,10 @@ blockquote { margin-bottom: 0px; } + .sidebar ol ul { + margin-left: 0px; + } + /* ------------------------------- PREFOOTER ------------------------------ */ diff --git a/docs/provisioners/chef_solo.md b/docs/provisioners/chef_solo.md index 5ddc56cdc..1c6b63232 100644 --- a/docs/provisioners/chef_solo.md +++ b/docs/provisioners/chef_solo.md @@ -155,7 +155,7 @@ Vagrant::Configure.run do |config| end {% endhighlight %} -## Configuring the Server Path +## Configuring the Temporary Path In order to run chef, Vagrant has to mount the specified cookbooks directory as a shared folder on the virtual machine. By default, this is set to be `/tmp/vagrant-chef`, @@ -185,4 +185,4 @@ end Once enabled, if you are building a VM from scratch, run `vagrant up` and provisioning will automatically occur. If you already have a running VM and don't want to rebuild everything from scratch, run `vagrant reload` and it will restart the VM, without completely -destroying the environment first, allowing the import step to be skipped. \ No newline at end of file +destroying the environment first, allowing the import step to be skipped. From 0c227858f9ea1a2e1f19cfef9343de952a62a046 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Sat, 31 Jul 2010 11:05:52 -0700 Subject: [PATCH 09/10] Negative margin on the list underneath the numbered list --- css/screen.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/css/screen.css b/css/screen.css index 4d89546c7..ce5db788d 100644 --- a/css/screen.css +++ b/css/screen.css @@ -314,7 +314,7 @@ blockquote { } .sidebar ol ul { - margin-left: 0px; + margin-left: -10px; } /* ------------------------------- From 2219900362fc8b96c9d80f5acd124023cc61b4d5 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Sat, 31 Jul 2010 11:18:15 -0700 Subject: [PATCH 10/10] Added documentation for remote chef solo (specifying recipe URL) --- _layouts/documentation.html | 1 + docs/provisioners/chef_solo.md | 10 ++-- docs/provisioners/chef_solo_remote.md | 70 +++++++++++++++++++++++++++ 3 files changed, 76 insertions(+), 5 deletions(-) create mode 100644 docs/provisioners/chef_solo_remote.md diff --git a/_layouts/documentation.html b/_layouts/documentation.html index 55abd090d..9d52d6d6b 100644 --- a/_layouts/documentation.html +++ b/_layouts/documentation.html @@ -8,6 +8,7 @@
  • Provisioners diff --git a/docs/provisioners/chef_solo.md b/docs/provisioners/chef_solo.md index 1c6b63232..4bff8bf33 100644 --- a/docs/provisioners/chef_solo.md +++ b/docs/provisioners/chef_solo.md @@ -34,7 +34,7 @@ various cookbooks. To tell Vagrant what the cookbook path is, set it up in your Vagrantfile, like so: {% highlight ruby %} -Vagrant::Configure.run do |config| +Vagrant::Config.run do |config| # This path will be expanded relative to the project directory config.chef.cookbooks_path = "cookbooks" end @@ -48,7 +48,7 @@ end directory, and chef solo will then look in every directory for the cookbooks. {% highlight ruby %} -Vagrant::Configure.run do |config| +Vagrant::Config.run do |config| config.chef.cookbooks_path = ["cookbooks", "~/company/cookbooks"] end {% endhighlight %} @@ -130,7 +130,7 @@ But sometimes, cookbooks need additional, custom JSON configuration. For this you can specify additional JSON data in the Vagrantfile: {% highlight ruby %} -Vagrant::Configure.run do |config| +Vagrant::Config.run do |config| # merge is used to preserve the default JSON configuration, otherwise it'll # all be overwritten config.chef.json.merge!({ @@ -148,7 +148,7 @@ to a directory containing these role files, and these roles can then be used by chef solo run list. An example of configuring roles is shown below: {% highlight ruby %} -Vagrant::Configure.run do |config| +Vagrant::Config.run do |config| # The roles path will be expanded relative to the project directory config.chef.roles_path = "roles" config.chef.add_role("web") @@ -163,7 +163,7 @@ and this should be fine for most users. But in the case that you need to customi the location, you can do so in the Vagrantfile: {% highlight ruby %} -Vagrant::Configure.run do |config| +Vagrant::Config.run do |config| config.chef.provisioning_path = "/tmp/vagrant-chef" end {% endhighlight %} diff --git a/docs/provisioners/chef_solo_remote.md b/docs/provisioners/chef_solo_remote.md new file mode 100644 index 000000000..109c331dc --- /dev/null +++ b/docs/provisioners/chef_solo_remote.md @@ -0,0 +1,70 @@ +--- +layout: documentation +title: Documentation - Provisioners - Chef Solo (Remote) +--- +# Chef Solo Provisioning (Remote) + +**Before reading this page, be sure to read the [chef solo provisioning](/docs/provisioners/chef_solo.html).** + +[Chef Solo](http://wiki.opscode.com/display/chef/Chef+Solo) also allows for an additional option +of downloading packaged (`tar.gz`) cookbooks from a remote URL to provision. This is a bit more +complicated than using a local cookbooks path (covered in the chef solo provisioning documentation), +but is less complicated than setting up a full blown chef server. + +Prior to reading this page, it is recommend that you spend a few minutes reading about +[running chef solo from a URL](http://wiki.opscode.com/display/chef/Chef+Solo#ChefSolo-RunningfromaURL). +This will allow you to familiarize yourself with the terms used throughout the rest of +this page. + +## Setting the Recipe URL + +The first step is specify the recipe URL in the Vagrantfile. This is the URL from +which chef solo will download the cookbooks. The Vagrantfile below shows how this is +done: + +{% highlight ruby %} +Vagrant::Config.run do |config| + config.vm.provisioner = :chef_solo + config.chef.recipe_url = "http://files.vagrantup.com/getting_started/cookbooks.tar.gz" +end +{% endhighlight %} + +## Setting the Cookbooks Path + +Next, you must specify the paths within the downloaded package where the cookbooks +are. By default, Vagrant assumes they're in a top-level "cookbooks" directory within +the package, but sometimes you may include other directories, such as "site-cookbooks" +which you must manually specify. + +To tell Vagrant what the cookbook path is, you use the same `config.chef.cookbooks_path` +setting, but with a little extra formatting to let Vagrant know you're describing a +path on the VM, and not on the host machine. + +{% highlight ruby %} +Vagrant::Config.run do |config| + config.chef.cookbooks_path = [:vm, "cookbooks"] +end +{% endhighlight %} + +You may also use an array to specify multiple cookbook paths. + +
    +

    Mixing Host and VM Cookbook Paths

    +

    + You can also mix together host and VM cookbook paths. This allows + you to use some cookbooks from a remote location, and some from a + local directory. An example of this is shown below: + +{% highlight ruby %} +Vagrant::Config.run do |config| + config.chef.cookbooks_path = ["local-cookbooks", [:vm, "cookbooks"]] +end +{% endhighlight %} +

    +
    + +## Enabling and Executing + +Now that everything is setup, provisioning the VM is the same as always: if you're +building the VM from scratch, just run `vagrant up`. Otherwise, run `vagrant reload` +to simply restart the VM, provisioning in the process.