diff --git a/_layouts/documentation.html b/_layouts/documentation.html index 72c4ed4ca..482bf24cd 100644 --- a/_layouts/documentation.html +++ b/_layouts/documentation.html @@ -5,7 +5,13 @@
  • Overview
  • Commands
  • Vagrantfile
    • -
  • Provisioning
    • +
  • Provisioners + +
  • Boxes
  • Base Boxes
  • Rake Integration
    • diff --git a/css/screen.css b/css/screen.css index c58f20c70..39b03c448 100644 --- a/css/screen.css +++ b/css/screen.css @@ -158,6 +158,7 @@ blockquote { .info { padding-left: 52px; + padding-right: 15px; margin-top: 0px; margin-bottom: 10px; border: 1px dotted #DDD; diff --git a/docs/provisioners.md b/docs/provisioners.md new file mode 100644 index 000000000..cf39b320a --- /dev/null +++ b/docs/provisioners.md @@ -0,0 +1,38 @@ +--- +layout: documentation +title: Documentation - Provisioners +--- +# Provisioners + +Vagrant supports provisioning a project's VM through the use of _provisioners_, +since spinning up a blank virtual machine is not very useful! The provisioners +supported out-of-the-box with a Vagrant installation are: [Chef Solo](/docs/provisioners/chef_solo.html) and +[Chef Server](/docs/provisioners/chef_server.html). These provisioners allow +you to easily setup your virtual machine with everything it needs to run as +a proper server (whether it be a web server, database server, utility server, +or all those things combined). + +By default, Vagrant disables provisioning. Provisioning can be enabled by selecting +the provisioner using the `config.vm.provisioner` configuration key. The value +of this key is either a symbol to use a built-in provisioner, a class which +inherits from `Vagrant::Provisioners::Base` for a custom solution, or `nil` +to disable it. + +## Which Provisioner Should I Use? + +Ah, with the freedom of choice comes the complication of choosing +what is right for you. + +* **Chef Solo** - Chef solo is most ideal if you're just getting started with + chef or a chef server is simply too heavy for your situation. Chef solo allows + you to embed all your cookbooks within your project as well, which is nice for + projects which want to keep track of their cookbooks within the same repository. + Chef solo runs standalone -- it requires no chef server or any other server to + talk to; it simply runs by itself on the VM. +* **Chef Server** - Chef server is useful for companies or individuals which + manage many projects, since it allows you to share cookbooks across multiple + projects. The cookbooks themselves are stored on the server, and the client + downloads the cookbooks upon running. +* **Puppet, shell scripts, etc.** - Do you use something other than that which + is built into Vagrant? Provisioners are simply subclasses of `Vagrant::Provisioners::Base`, + meaning you can easily build your own, should the need arise. \ No newline at end of file diff --git a/docs/provisioners/chef_server.md b/docs/provisioners/chef_server.md new file mode 100644 index 000000000..24d303c5b --- /dev/null +++ b/docs/provisioners/chef_server.md @@ -0,0 +1,7 @@ +--- +layout: documentation +title: Documentation - Provisioners - Chef Server +--- +# Chef Server Provisioning + +Coming soon. \ No newline at end of file diff --git a/docs/provisioners/chef_solo.md b/docs/provisioners/chef_solo.md new file mode 100644 index 000000000..96bbefe27 --- /dev/null +++ b/docs/provisioners/chef_solo.md @@ -0,0 +1,173 @@ +--- +layout: documentation +title: Documentation - Provisioners - Chef Solo +--- +# Chef Solo Provisioning + +[Chef Solo](http://wiki.opscode.com/display/chef/Chef+Solo) allows you to provision your virtual +machine with [Chef Cookbooks](http://wiki.opscode.com/display/chef/Cookbooks) without requiring a +[Chef Server](http://wiki.opscode.com/display/chef/Chef+Server). At a very basic level, [chef](http://www.opscode.com/chef/) +is an open source systems integration framework which automates tasks through programmable "cookbooks." +This page will not go into the details of creating custom chef cookbooks, since that +is covered in detail around the web, but a good place to start is the [opscode cookbooks repository](http://github.com/opscode/cookbooks) +which contains cookbooks for most of the popular server software already made. + +## Setting the Cookbooks Path + +First, Vagrant needs to know where the cookbooks are located. By default, Vagrant will +look in the "cookbooks" directory relative to the root of the project directory (where +a project's Vagrantfile is). The cookbooks directory should have a structure similar to +the following: + +{% highlight bash %} +$ ls cookbooks/ +apache2/ +passenger_apache2/ +rails/ +sqlite/ +vagrant_main/ +{% endhighlight %} + +Basically, the cookbooks directory should immediately contain all the folders of the +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| + # This path will be expanded relative to the project directory + config.chef.cookbooks_path = "cookbooks" +end +{% endhighlight %} + +
    +

    Multiple Cookbook Paths

    +

    + You can also specify multiple cookbook paths by making the configuration an + array of file paths. Every file path will be expanded relative to the project + directory, and chef solo will then look in every directory for the cookbooks. + +{% highlight ruby %} +Vagrant::Configure.run do |config| + config.chef.cookbooks_path = ["cookbooks", "~/company/cookbooks"] +end +{% endhighlight %} +

    +
    + +## Configuring the Main Cookbook + +By default, Vagrant is configured to run a single cookbook called `vagrant_main`. +This cookbook is known as the "vagrant main cookbook" and is analogous to the +main entry point of an executable program. This main cookbook should include +other cookbooks in the order they should be run to setup the system. + +An example `vagrant_main` default recipe file is shown below: + +{% highlight ruby %} +# vagrant_main cookbook +# This cookbook includes and sets up a server with apache, mysql, +# rails, and passenger. It finally runs a custom cookbook to configure +# the application. +# +require_recipe "apache2" +require_recipe "mysql" +require_recipe "rails" +require_recipe "passenger_apache2::mod_rails" +require_recipe "my_custom_application" +{% endhighlight %} + +If you want Vagrant to use a cookbook other than `vagrant_main` as the default, +this can be changed using the Vagrantfile: + +{% highlight ruby %} +Vagrant::Config.run do |config| + config.chef.run_list.clear + config.chef.add_recipe("my_recipe") +end +{% endhighlight %} + +
    +

    Why the main cookbook at all?

    +

    + Some people ask, "Why does Vagrant default to the vagrant_main cookbook at all?" + The reason is that its more portable to require all recipes within a single cookbook + than to define them all using add_recipe in the Vagrantfile. By + requiring all the recipes in a single meta-cookbook, you can then reuse that cookbook + for production environments and so on. Vagrant is basically encouraging you + to write more portable cookbooks! +

    +

    + Of course, if you don't like this, you're free to define your own recipes + as shown above. +

    +
    + +## JSON Configuration + +Every chef cookbook has access to the `node` variable which is a hash containing +server-specific configuration options which can be used to control provisioning. +By default, Vagrant JSON configuration looks like the following: + +{% highlight ruby %} +{ + :instance_role => "vagrant", + :vagrant => { + :config => { ... }, # Full Vagrant config + :directory => "/vagrant" # Or wherever configured project directory is + } +} +{% endhighlight %} + +This JSON configuration is specifically thought out such that the `instance_role` +key could be used so that cookbooks could be shared between production and development, +possibly tweaking paths or configuration based on the `instance_role`. And +`project_directory` is useful if you're setting up a VirtualHost for a web server, +for example, and need to set the path to the public directory within your +`project_directory`. + +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| + # merge is used to preserve the default JSON configuration, otherwise it'll + # all be overwritten + config.chef.json.merge!({ + :load_limit => 42, + :chunky_bacon => true + }) +end +{% endhighlight %} + +## Configuring the Server 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`, +and this should be fine for most users. But in the case that you need to customize +the location, you can do so in the Vagrantfile: + +{% highlight ruby %} +Vagrant::Configure.run do |config| + config.chef.provisioning_path = "/tmp/vagrant-chef" +end +{% endhighlight %} + +This folder is created for provisioning purposes and destroyed once provisioning +is complete. + +## Enabling and Executing + +Finally, once everything is setup, provisioning can be enabled and run. To enable +provisioning, tell Vagrant to use chef solo in the Vagrantfile: + +{% highlight ruby %} +Vagrant::Config.run do |config| + config.vm.provisioner = :chef_solo +end +{% endhighlight %} + +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 provisioning will automatically +occur. \ No newline at end of file diff --git a/docs/provisioners/others.md b/docs/provisioners/others.md new file mode 100644 index 000000000..b7ffbcc2d --- /dev/null +++ b/docs/provisioners/others.md @@ -0,0 +1,7 @@ +--- +layout: documentation +title: Documentation - Provisioners - Others +--- +# Provisioning with Other Tools + +Coming soon. \ No newline at end of file