haskal
/
vagrant
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge branch 'docs' into gh-pages

This commit is contained in:
Mitchell Hashimoto 2010-07-31 11:23:24 -07:00
parent 25d7d4315d 2219900362
commit 1a82a36da4
19 changed files with 248 additions and 230 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
_includes/header.html
View File

@ -34,7 +34,7 @@
</div>
<div id="content" class="container_12 clearfix">
<div class="grid_12 notice">
<!--<div class="grid_12 notice">
Vagrant 0.5 has been released! Read the <a href="/docs/changes/changes_04x_05x.html">full list of changes</a>.
</div>
</div>-->

1
_layouts/documentation.html
View File

@ -8,6 +8,7 @@
<li><a href="/docs/provisioners.html">Provisioners</a>
<ul>
<li><a href="/docs/provisioners/chef_solo.html">Chef Solo</a></li>
<li><a href="/docs/provisioners/chef_solo_remote.html">Chef Solo (Remote)</a></li>
<li><a href="/docs/provisioners/chef_server.html">Chef Server</a></li>
<li><a href="/docs/provisioners/others.html">Others</a></li>
</ul>

4
css/screen.css
View File

@ -313,6 +313,10 @@ blockquote {
margin-bottom: 0px;
}
.sidebar ol ul {
margin-left: -10px;
}
/* -------------------------------
PREFOOTER
------------------------------ */

10
docs/boxes.md
View File

@ -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 %}

4
docs/converting_password_to_key_ssh.md
View File

@ -14,7 +14,7 @@ key-based SSH.
<h3>We updated our boxes!</h3>
<p>
If you're not using a custom base box, and you're using one of the base
boxes we created (<code>getting_started.box</code>, <code>base.box</code>, etc.),
boxes we created (<code>lucid32.box</code>, <code>lucid64.box</code>, etc.)
then just remove your old box and download the new one. We updated all
of our boxes to work with <code>0.2.x</code>!
</p>
@ -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.
your previously broken box.

48
docs/getting-started/boxes.md
View File

@ -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 %}

6
docs/getting-started/index.md
View File

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

4
docs/getting-started/introduction.md
View File

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

26
docs/getting-started/packaging.md
View File

@ -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`.
@ -55,19 +51,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

27
docs/getting-started/ports.md
View File

@ -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)
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.

116
docs/getting-started/provisioning.md
View File

@ -6,111 +6,63 @@ 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`:
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-instance ~$ which htop
/usr/bin/htop
{% endhighlight %}
vagrant@vagrantup:~$ wget -qO- 127.0.0.1
<h1>Hello from a Vagrant VM</h1>
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.

13
docs/getting-started/rebuild.md
View File

@ -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 extraneous software, etc.

27
docs/getting-started/setup.md
View File

@ -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 "<h1>Hello from a Vagrant VM</h1>" > 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.
<div class="info">
<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>

6
docs/getting-started/setup/ubuntu.md
View File

@ -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 %}

41
docs/getting-started/ssh.md
View File

@ -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,12 +15,13 @@ 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
...
Welcome to your vagrant instance!
Last login: Fri Mar 5 23:21:47 2010 from 10.0.2.2
vagrant@vagrantbase:~$
vagrant@vagrantup:~$
{% endhighlight %}
<div class="info">
@ -40,35 +41,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.**

55
docs/getting-started/teardown.md
View File

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

14
docs/provisioners/chef_solo.md
View File

@ -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,14 +148,14 @@ 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")
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`,
@ -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 %}
@ -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.
destroying the environment first, allowing the import step to be skipped.

70
docs/provisioners/chef_solo_remote.md Normal file
View File

@ -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.
<div class="info">
<h3>Mixing Host and VM Cookbook Paths</h3>
<p>
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 %}
</p>
</div>
## 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.

2
index.md
View File

@ -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 %}