elzar 0.1.2 → 0.2.0

data/.gitignore

@@ -1 +1,4 @@
 /.vagrant
+.idea
+pkg
+provision

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.2.0
+* Drop support for relevance_rails
+* Update DNA to be opinionated, to support Ruby 1.9.3
+  (as opposed to REE) and Postgres (as opposed to MySQL)
+* Update CLI commands and options. (See USAGE.md.)
+
 ## 0.1.0
 * Initial working version for relevance_rails
 

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in elzar.gemspec
+gemspec

data/Gemfile.lock

@@ -1,96 +1,59 @@
-GIT
-  remote: git://github.com/sumbach/knife-github-cookbooks.git
-  revision: 13d5d7444b468cab24e6fa2d4b07da6ea45ac088
+PATH
+  remote: .
   specs:
-    knife-github-cookbooks (0.1.5)
-      chef (~> 0.10.0)
-      launchy (~> 0.4.0)
+    elzar (0.2.0)
+      fog (~> 1.5.0)
+      gli (~> 2.0.0)
+      multi_json (~> 1.3.0)
+      slushy (~> 0.1.3)
 
 GEM
   remote: http://rubygems.org/
   specs:
-    archive-tar-minitar (0.5.2)
-    bunny (0.7.9)
-    chef (0.10.8)
-      bunny (>= 0.6.0)
-      erubis
-      highline
-      json (>= 1.4.4, <= 1.6.1)
-      mixlib-authentication (>= 1.1.0)
-      mixlib-cli (>= 1.1.0)
-      mixlib-config (>= 1.1.2)
-      mixlib-log (>= 1.3.0)
-      moneta
-      net-ssh (~> 2.1.3)
-      net-ssh-multi (~> 1.1.0)
-      ohai (>= 0.6.0)
-      rest-client (>= 1.0.4, < 1.7.0)
-      treetop (~> 1.4.9)
-      uuidtools
-    configuration (1.3.1)
-    erubis (2.7.0)
-    ffi (1.0.11)
-    highline (1.6.11)
-    i18n (0.6.0)
-    ipaddress (0.8.0)
-    json (1.5.2)
-    knife-solo (0.0.4)
-      chef (~> 0.10.0)
-      net-ssh (~> 2.1.3)
-    launchy (0.4.0)
-      configuration (>= 0.0.5)
-      rake (>= 0.8.1)
-    mime-types (1.18)
-    mixlib-authentication (1.1.4)
-      mixlib-log
-    mixlib-cli (1.2.2)
-    mixlib-config (1.1.2)
-    mixlib-log (1.3.0)
-    moneta (0.6.0)
+    bahia (0.7.2)
+      open4 (~> 1.3.0)
+    builder (3.1.3)
+    diff-lcs (1.1.3)
+    excon (0.16.2)
+    fog (1.5.0)
+      builder
+      excon (~> 0.14)
+      formatador (~> 0.2.0)
+      mime-types
+      multi_json (~> 1.0)
+      net-scp (~> 1.0.4)
+      net-ssh (>= 2.1.3)
+      nokogiri (~> 1.5.0)
+      ruby-hmac
+    formatador (0.2.3)
+    gli (2.0.0)
+    jruby-pageant (1.1.1)
+    mime-types (1.19)
+    multi_json (1.3.6)
     net-scp (1.0.4)
       net-ssh (>= 1.99.1)
-    net-ssh (2.1.4)
-    net-ssh-gateway (1.1.0)
-      net-ssh (>= 1.99.1)
-    net-ssh-multi (1.1)
-      net-ssh (>= 2.1.4)
-      net-ssh-gateway (>= 0.99.0)
-    ohai (0.6.12)
-      ipaddress
-      mixlib-cli
-      mixlib-config
-      mixlib-log
-      systemu
-      yajl-ruby
-    polyglot (0.3.3)
+    net-ssh (2.6.0)
+      jruby-pageant (>= 1.1.1)
+    nokogiri (1.5.5)
+    open4 (1.3.0)
     rake (0.9.2.2)
-    rest-client (1.6.7)
-      mime-types (>= 1.16)
-    systemu (2.5.0)
-    thor (0.14.6)
-    treetop (1.4.10)
-      polyglot
-      polyglot (>= 0.3.1)
-    uuidtools (2.1.2)
-    vagrant (0.8.7)
-      archive-tar-minitar (= 0.5.2)
-      erubis (~> 2.7.0)
-      i18n (~> 0.6.0)
-      json (~> 1.5.1)
-      net-scp (~> 1.0.4)
-      net-ssh (~> 2.1.4)
-      thor (~> 0.14.6)
-      virtualbox (~> 0.9.1)
-    virtualbox (0.9.2)
-      ffi (~> 1.0.9)
-    yajl-ruby (1.1.0)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.2)
+    ruby-hmac (0.4.0)
+    slushy (0.1.3)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  chef (= 0.10.8)
-  json (= 1.5.2)
-  knife-github-cookbooks!
-  knife-solo (= 0.0.4)
-  vagrant (= 0.8.7)
+  bahia
+  bundler
+  elzar!
+  rake (~> 0.9.2.2)
+  rspec

data/README.md

@@ -1,22 +1,11 @@
 ## Description
+
 This gem enables a Rails app to define custom Chef recipes while still using an awesome default set
-of Chef recipes. Best used in conjunction with relevance\_rails and slushy. Includes recipes for
-ruby 1.9, ree, mysql, postgresql and nginx/passenger.
+of Chef recipes. Includes recipes for Ruby 1.9, postgresql, and nginx/passenger.
 
 ## Usage
 
-To use Elzar with your Rails app, just use (relevance_rails)[https://github.com/relevance/relevance_rails].
-
-But if you'd like to manually do it:
-
-```ruby
-# Creates a provision/ directory to define app-specific cookbooks
-Elzar.create_provision_directory 'provision'
-
-# To combine Elzar's cookbooks with your app's cookbooks
-dir = Elzar.merge_and_create_temp_directory 'provision'
-# You now have a directory you can put on a chef node
-```
+To use Elzar with your Rails app, see [USAGE.md](https://github.com/relevance/elzar/blob/master/USAGE.md).
 
 ## Local Development
 
@@ -26,9 +15,12 @@ If you'd like to try these Chef cookbooks with Vagrant:
 $ git clone git@github.com:relevance/elzar.git
 $ cd elzar
 $ gem install bundler
-# creates provision/ for local vagrant use
+
+# creates a `provision` directory for local vagrant use
 $ rake bam
+
 $ cd provision
+$ vim dna.json # edit DNA file to give a name to your Rails app with no whitespace (e.g., "my_sample_app")
 $ bundle install
 
 ## Using Vagrant
@@ -40,7 +32,7 @@ your bundle and grab the Ubuntu Lucid VM image.
     vagrant box add lucid64 http://files.vagrantup.com/lucid64.box
 
 ```sh
-## Spin up a new VM
+## Spin up a new VM and run the Chef recipes on it
 $ vagrant up
 
 ## SSH into the VM
@@ -57,6 +49,16 @@ $ vagrant suspend
 $ vagrant resume
 ```
 
+### CLI Development
+
+The CLI tool (bin/elzar) is built on top of [GLI](https://github.com/davetron5000/gli)
+which is a command line parser modelled after Git. Normally any
+exception that occurs while running a command results in only the error
+message being displayed, not the backtrace. If you would like to view
+the backtrace you must set the env variable `GLI_DEBUG=true`.
+
+    GLI_DEBUG=true bundle exec bin/elzar foo
+
 ## Issues
 
-Please file issues [on github](https://github.com/relevance/elzar/issues).
+Please file issues [on GitHub](https://github.com/relevance/elzar/issues).

data/USAGE.md

@@ -0,0 +1,257 @@
+Elzar Usage
+===========
+
+## Rails Tutorial
+
+This example assumes that you have a working Rails application that is
+compatible with the default [Rails DNA](/relevance/elzar/tree/master/lib/elzar/templates/dna/rails.json)
+included in Elzar.
+
+All commands assume your `RAILS_ROOT` is your current working directory.
+
+### Step 0: Install Elzar
+
+```sh
+gem install elzar
+```
+
+
+### Step 1: Initialize Elzar's Provision Directory
+
+This creates a `provision/` directory inside of your project. This
+folder will be used to hold configuration data, custom Chef recipes,
+and the `dna.json` file which specifies how configuration data to
+the Chef recipes themselves.
+
+```sh
+elzar init --dna=rails
+```
+
+
+### Step 2: Configure dna.json
+
+The previous command created a `dna.json` template at
+`provision/dna.json`. It will look roughly like so:
+
+```javascript
+{
+  "run_list":["role[plumbing]", "role[postgres_database]", "ruby", "passenger", "rails_app"],
+  "passenger":  {
+    "version":  "3.0.11",
+    "root_path":  "/opt/relevance-ruby/lib/ruby/gems/1.9.1/gems/passenger-3.0.11",
+    "module_path":  "/opt/relevance-ruby/lib/ruby/gems/1.9.1/gems/passenger-3.0.11/ext/apache2/mod_passenger.so"
+  },
+  "ruby":  {
+    "version":  "1.9.3-p194",
+    "url":  "http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.3-p194.tar.gz"
+  },
+  "rails_app":  {
+    "name":  "TODO: Replace with the name of your Rails app"
+  }
+}
+```
+
+This file specifies which recipes Chef will run and how they will be
+ran. For example, you can edit the `run_list` to run a custom
+recipe that you have created or swap out one of the default recipes for
+another (e.g. mysql for postgresql).
+
+At the very least you will need to specify `rails_app[name]`. For
+example:
+
+```javascript
+"rails_app":  {
+  "name": "elzar_rails_example"
+}
+```
+
+The `rails_app[name]` in `dna.json` has several implicit effects:
+
+* It determines where your app lives on the file system (e.g.,
+  `/var/www/apps/elzar_rails_example/`)
+* It determines the name of your database (e.g.,
+  `elzar_rails_example_production`)
+* It determines the path of your nginx configuration file (e.g.,
+  `/etc/nginx/sites-enabled/elzar_rails_example`)
+
+You'll want to consider how your choice of `rails_app` name will operate
+in these contexts (e.g.,  whether your database engine allows
+dashes in its database names).
+
+
+### Step 3: Configure AWS Settings
+
+The `init` command also created 2 separate AWS configuration files:
+
+* `provision/aws_config.yml` - holds non-sensitive settings, which
+  you're comfortable checking into Git
+* `provision/aws_config.private.yml` - holds (wait for it) private
+  settings, which you should **not** check into Git
+
+These files look like so:
+
+```yaml
+# aws_config.yml
+server:
+  creation_config:
+    flavor_id: <instance type, e.g. 'm1.large'>
+    image_id: <AMI to bootstrap with; must be some Ubuntu server image; e.g., "ami-fd589594" for Ubuntu 11.04>
+    groups: <security group to place the new deployment in, e.g. "default">
+    key_name: <name of the public/private keypair to start instance with>
+```
+
+```yaml
+# aws_config.private.yml
+aws_credentials:
+  aws_access_key_id: <your aws access key id>
+  aws_secret_access_key: <your aws secret access key>
+
+server:
+  private_key: |
+    -----BEGIN RSA PRIVATE KEY-----
+    Include the RSA private key here. This should correspond to the keypair indicated
+    by server[:creation_config][:key_name] in aws_config.yml.
+    -----END RSA PRIVATE KEY-----
+```
+
+Elzar will load both of these files and perform a deep merge on them.
+Any settings in `aws_config.private.yml` will override settings found in
+`aws_config.yml`.
+
+Edit these files as appropriate for your project.
+
+
+### Step 4: Preheat Your Server
+
+This step will provision a new server from AWS using your specified
+credentials and will bootstrap Chef Solo on the box.
+
+Note: **A *new* EC2 instance is provisioned each time this script is
+executed**; you'll probably want to clean up those instances if you need
+to re-start for any reason.
+
+```sh
+elzar preheat "ElzarRailsExample Staging"
+```
+
+In this case, Elzar will provision a new instance and tag it with a name
+of "ElzarRailsExample Staging". This is the name that you will see when browsing
+instances in the AWS console. Name your instance accordingly.
+
+If this step completes successfully, it will display the ID of the
+instance, which you'll use in the next step, as well as its public IP address. For example:
+
+```
+Finished Provisioning Server
+Instance ID: i-abcdef01
+Instance IP: 42.42.000.42
+````
+
+
+### Step 5: Cook the Recipes
+
+This step is responsible for combining your custom recipes (if any) and
+configuration with the default recipes that ship with Elzar. The
+combined payload will be uploaded to the server and placed in
+`/tmp/chef-solo` where they will run.
+
+
+```sh
+elzar cook [YOUR-INSTANCE-ID]
+```
+
+
+### Step 6: Configure Capistrano
+
+At this point in time, we have a server that is ready to run our app.
+Now, we just need to get our app up there.
+
+First off, we need to add Capistrano and [capistrano-relevance](https://github.com/relevance/capistrano-relevance) to our Rails app.
+To do so, add these lines to the `Gemfile` in the Rails application:
+
+```ruby
+group :deployment do
+  gem 'capistrano', :git => 'git://github.com/capistrano/capistrano', :ref => 'b31e2f5'
+  gem 'capistrano-relevance'
+end
+```
+
+And then execute:
+
+```sh
+bundle
+bundle exec capify .
+```
+
+Next, we need to customize `config/deploy.rb` for our app.
+(For the purposes of this tutorial, we'll assume that we want the default capistrano-relevance configuration. For alternative setups, and for more information on capistrano-relevance, check out its [README](https://github.com/relevance/capistrano-relevance/blob/master/README.md).)
+
+*Replace* the existing contents of `config/deploy.rb` with a structure like so:
+
+```ruby
+require 'bundler/capistrano'
+require 'capistrano/relevance/all'
+
+set :application, "elzar_rails_example"                      # TODO Replace with *your* app name
+set :repository,  "git://github.com/you/elzar_rails_example" # TODO Replace with *your* repo
+
+role :web, "42.42.000.42"                                    # TODO Replace with the IP address for *your* EC2 instance
+role :app, "42.42.000.42"                                    # TODO Replace with the IP address for *your* EC2 instance
+role :db,  "42.42.000.42", :primary => true                  # TODO Replace with the IP address for *your* EC2 instance
+```
+
+
+### Step 7: Prepare to Serve
+
+Now that we have a working Capistrano configuration we just need to make a couple of other small tweaks to make the box deployable.
+Specifically, we need to create the directory structure that Capistrano expects and place our database configuration on the box.
+
+Best practices (TM) discourage us from checking in any database credentials into our Git repo.
+Instead, we can create a `database.yml` file on the server.
+
+```sh
+bundle exec cap deploy:setup
+
+ssh deploy@42.42.000.42
+
+# Create the the directory where you will store your shared configuration.
+mkdir /var/www/apps/[YOUR-APP-NAME]/shared/config
+
+# Add production settings for the database
+vim /var/www/apps/[YOUR-APP-NAME]/shared/config/database.yml
+
+# We're done messing around on the server; let's get outta here
+exit
+```
+
+Your `database.yml` file should look similar to this one, obviously edited to meet your application's needs.
+
+```yaml
+production:
+  adapter: postgresql
+  encoding: unicode
+  database: [YOUR-APP-NAME]_production
+  pool: 5
+  username: deploy
+  password: d3pl0y-p0stgr3s
+```
+
+
+### Step 8: Serve It Up
+
+Here comes the exciting part.
+It's time to deploy our Rails app to the box.
+Since this is the first time we've ever deployed to the box we'll need to run a special Capistrano command that does slightly more work than a bare deploy.
+
+```sh
+# execute from RAILS_ROOT on your localhost
+bundle exec cap deploy:cold
+```
+
+Congratulations! You should be able to visit the IP address using your favorite browser and see the application up and running.
+
+For subsequent deploys, you can simply run:
+
+```sh
+bundle exec cap deploy
+```