Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Set up a cold, inhospitable system using Terraform.

tree: b2fc329664

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 test
Octocat-spinner-32 .gitignore
Octocat-spinner-32 Gemfile
Octocat-spinner-32 README.markdown
Octocat-spinner-32 Rakefile
Octocat-spinner-32 terraform.gemspec
README.markdown

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 "pygments" do
  met? { in_path? "pygmentize" }         # Check if your dependency is met.
  meet { shell "pip install pygments" }  # Install your dependency.
end

...

satisfy_dependencies()

The Terraform DSL provides these functions which are commonly used when provisioning systems to run web services:

shell(command) Executes a shell command.
in_path?(command) True if the command is in the current path.
package_installed?(package_name) True if an apt-get package is installed.
ensure_packages(*package_names) Ensures the given packages are installed via apt-get.
ensure_ppa(ppa_url) Ensures the given PPA (used on Ubuntu) is installed. "ppa_url" is of the form "ppa:user/name".
gem_installed?(name) True if the given Ruby gem is installed.
ensure_gem(name) Ensures the given Ruby gem is installed.
ensure_rbenv() Ensures rbenv is installed.
ensure_rbenv_ruby(ruby_version) Ensures the given version of Ruby is installed. `ruby_version` is an rbenv Ruby version string like "1.9.2.-p290".
ensure_run_once(dependency_name, block) Runs the given block once. Use for tasks that you're too lazy to write a proper `met?` block for, like running database migrations.
ensure_file(source_path, dest_path, on_change) 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.
fail_and_exit(message) Use when your meet() block encounters an error and cannot satisfy a dependency.

For further details, see the source. 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, which makes use of the DSL quite a bit.

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, and its Fezzik deploy script here.

Contribute

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 => "~/path/to/terraform_checkout"

Credits

Something went wrong with that request. Please try again.