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.