terraform 0.0.2 → 0.0.3

data/README.markdown

@@ -1,26 +1,123 @@
-Terraform is a small goal-oriented DSL for setting up a machine, similar in purpose to Chef and Puppet. Its
-design is inspired by Babushka, but it's simpler and tailored specifically for provisioning a machine for a
-webapp.
+Terraform
+---------
+
+Terraform is a small goal-oriented Ruby DSL for setting up a machine, similar in purpose to Chef and Puppet,
+but without the complexity. It's tailored for the kinds of tasks needed for deploying web apps and is designed
+to be refreshingly easy to understand and debug. You can read through the entire Terraform library in two
+minutes and know precisely what it will and won't do for you. Its design is inspired by Babushka.
 
 Usage
 -----
+This is the basic structure of a system provisioning script written using Terraform:
 
     require "terraform_dsl"
-    include Terraform::Dsl
-    dep "my library" do
-      met? { (check if your dependency is met) }
-      meet { (install your dependency) }
+    include Terraform::DSL
+
+    dep "pygments" do
+      met? { in_path? "pygmentize" }         # Check if your dependency is met.
+      meet { shell "pip install pygments" }  # Install your dependency.
     end
 
-A more detailed README is coming shortly.
+    ...
+
+    satisfy_dependencies()
+
+The Terraform DSL provides these functions which are commonly used when provisioning systems to run web services:
+
+<table>
+  <tr>
+    <td>shell(command)</td>
+    <td>Executes a shell command. Use this generally instead of backticks. It raises an exception if the exit
+        status of the command was nonzero, and prints the command string as well as the output.</td>
+  </tr>
+  <tr>
+    <td>in_path?(command)</td>
+    <td>True if the command is in the current path.</td>
+  </tr>
+  <tr>
+    <td>package_installed?(package_name)</td>
+    <td>True if a package is installed. Currently only apt-get is supported.</td>
+  </tr>
+  <tr>
+    <td>ensure_packages(*package_names)</td>
+    <td>Ensures the given packages are installed via apt-get.</td>
+  </tr>
+  <tr>
+    <td>ensure_ppa(ppa_url)</td>
+    <td>Ensures the given PPA (used on Ubuntu) is installed. "ppa_url" is of the form "ppa:user/name".</td>
+  </tr>
+  <tr>
+    <td>gem_installed?(name)</td>
+    <td>True if the given Ruby gem is installed.</td>
+  </tr>
+  <tr>
+    <td>ensure_gem(name)</td>
+    <td>Ensures the given Ruby gem is installed.</td>
+  </tr>
+  <tr>
+    <td>ensure_rbenv()</td>
+    <td>Ensures rbenv is installed.</td>
+  </tr>
+  <tr>
+    <td>ensure_rbenv_ruby(ruby_version)</td>
+    <td>Ensures the given version of Ruby is installed. `ruby_version` is an rbenv Ruby version string like
+        "1.9.2.-p290".</td>
+  </tr>
+  <tr>
+    <td>ensure_run_once(dependency_name, block)</td>
+    <td>Runs the given block once. Use for tasks that you're too lazy to write a proper `met?` block for, like running database migrations.</td>
+  </tr>
+  <tr>
+    <td>ensure_file(source_path, dest_path, on_change)</td>
+    <td>Ensures the file at dest_path is the exact same as the file at source_path. Use this for copying
+        configuration files (e.g. nginx.conf) to their proper locations.</td>
+  </tr>
+  <tr>
+    <td>fail_and_exit(message)</td>
+    <td>Use when your meet() block encounters an error and cannot satisfy a dependency.</td>
+  </tr>
+</table>
+
+For further details, see [the source](https://github.com/philc/terraform/blob/master/lib/terraform/dsl.rb).
+It's a short, well-documented file and there's no magic.
+
+Installation
+------------
+1. Install the Terraform gem on your local machine (the machine you're deploying from): `gem install
+terraform`
+
+2. Write your system provisioning script using the Terraform DSL.
+
+3. Copy your system provisioning script and the Terraform library (which is a single file) to your remote
+machine and run it. Do this as part of your deploy script.
+
+You can use the Terraform gem to write the Terraform library out to a single file as part of your deploy
+script, prior to copying it over to your remote machine:
+
+    require "terraform"
+    Terraform.write_dsl_file("/tmp/staging/my_app/terraform_dsl.rb")
+
+Terraform is designed to be run on a barebones machine with little preinstalled software. The only requirement
+is that some version (any version) of Ruby is installed on the machine you're provisioning.
+
+Examples
+--------
+See the [Terraform library itself](https://github.com/philc/terraform/blob/master/lib/terraform/dsl.rb), which
+makes use of the DSL quite a bit.
+
+[Barkeep](https://github.com/ooyala/barkeep) is a code review system which uses Terraform for provisioning the
+machines it gets deployed to. You can see its system provisioning script written using Terraform
+[here](https://github.com/ooyala/barkeep/blob/master/script/system_setup.rb), and its Fezzik deploy script
+[here](https://github.com/ooyala/barkeep/blob/master/config/tasks/deploy.rake).
 
 Contribute
 ----------
-When editing this gem, to test your changes, you can load your local copy of the gem in your project by using
-this in your Gemfile:
+When developing this gem you can quickly preview and test your changes by loading your local copy of the gem
+in your project's Gemfile:
 
-gem "terraform", :path => "~/p/terraform"
+    gem "terraform", :path => "~/path/to/terraform_checkout"
 
 Credits
 -------
-Dmac -- thanks for the name!
+* Daniel MacDougall ([dmacdougall](https://github.com/dmacdougall)) -- thanks for the name.
+* Caleb Spare ([cespare](https://github.com/cespare))

data/lib/terraform/dsl.rb

@@ -2,7 +2,7 @@ require "fileutils"
 require "digest/md5"
 
 module Terraform
-  module Dsl
+  module DSL
     def dep(name)
       @dependencies ||= []
       # If a dep gets required or defined twice, only run it once.
@@ -18,8 +18,8 @@ module Terraform
     def fail_and_exit(message) puts message; exit 1 end
 
     # Runs a command and raises an exception if its exit status was nonzero.
+    # Options:
     # - silent: if false, log the command being run and its stdout. False by default.
-    # - check_exit_code: raises an error if the command had a non-zero exit code. True by default.
     def shell(command, options = {})
       silent = (options[:silent] != false)
       puts command unless silent

data/lib/terraform/version.rb

@@ -1,3 +1,3 @@
 module Terraform
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: terraform
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: 
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Phil Crosby
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-03-27 00:00:00 -07:00
+date: 2012-04-17 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency