Permalink
Browse files

update readme to new style

  • Loading branch information...
hone committed Oct 21, 2011
1 parent 8ef8d07 commit e23113afc5850efacaab105660b758b14776ec03
Showing with 128 additions and 20 deletions.
  1. +128 −20 README.md
View
148 README.md
@@ -1,26 +1,143 @@
-# Ruby Language Pack
+Heroku buildpack: Ruby
+======================
-The Ruby Language Pack requires a `Gemfile` and `Gemfile.lock` file to be recognized as a ruby app. It will then proceed to run `bundle install` after setting up the appropriate environment for [ruby](http://ruby-lang.org) and [bundler](http://gembundler.com).
+This is a [Heroku buildpack](http://devcenter.heroku.com/articles/buildpack) for Ruby, Rack, and Rails apps. It uses [bundler](http://gembundler.com) for dependency management.
-## Bundler
+Usage
+-----
-For non-windows `Gemfile.lock` files, the `--deployment` flag will be used. The `vendor/bundle` directory is cached between builds to allow for faster `bundle install` times. `bundle clean` is used to ensure no stale gems are stored between builds.
+### Ruby
-## Rails
+Example Usage:
-A [rails_log_stdout](http://github.com/ddollar/rails_log_stdout) is installed by default so Rails' logger will log to STDOUT and picked up by Heroku's [logplex](http://github.com/heroku/logplex).
+ $ ls
+ Gemfile Gemfile.lock
-## Rails 3
+ $ heroku create --stack cedar --buildpack http://github.com/heroku/heroku-buildpack-ruby.git
-To enable static assets being served on the dyno, [rails3_serve_static_assets](http://github.com/pedro/rails3_serve_static_assets) is installed by default. If the [execjs gem](http://github.com/sstephenson/execjs) is detected then [node](http://github.com/joyent/node) will be vendored. The `assets:precompile` rake task will get run if no `public/manifest.yml` is detected. See [this article](http://devcenter.heroku.com/articles/rails31_heroku_cedar) on how rails 3.1 works on cedar.
+ $ git push heroku master
+ ...
+ -----> Heroku receiving push
+ -----> Fetching custom buildpack
+ -----> Ruby app detected
+ -----> Installing dependencies using Bundler version 1.1.rc
+ Running: bundle install --without development:test --path vendor/bundle --deployment
+ Fetching gem metadata from http://rubygems.org/..
+ Installing rack (1.3.5)
+ Using bundler (1.1.rc)
+ Your bundle is complete! It was installed into ./vendor/bundle
+ Cleaning up the bundler cache.
+ -----> Discovering process types
+ Procfile declares types -> (none)
+ Default types for Ruby -> console, rake
-## Auto Injecting Plugins
+The buildpack will detect your app as Ruby if it has a `Gemfile` and `Gemfile.lock` files in the root directory. It will then proceed to run `bundle install` after setting up the appropriate environment for [ruby](http://ruby-lang.org) and [bundler](http://gembundler.com).
+
+#### Bundler
+
+For non-windows `Gemfile.lock` files, the `--deployment` flag will be used. In the case of windows, the Gemfile.lock will be deleted and bundler will do a full resolve so native gems are handled properly. The `vendor/bundle` directory is cached between builds to allow for faster `bundle install` times. `bundle clean` is used to ensure no stale gems are stored between builds.
+
+### Rails 2
+
+Example Usage:
+
+ $ ls
+ app config db doc Gemfile Gemfile.lock lib log public Rakefile README script test tmp vendor
+
+ $ ls config/environment.rb
+ config/environment.rb
+
+ $ heroku create --stack cedar --buildpack http://github.com/heroku/heroku-buildpack-ruby.git
+
+ $ git push heroku master
+ ...
+ -----> Heroku receiving push
+ -----> Ruby/Rails app detected
+ -----> Installing dependencies using Bundler version 1.1.rc
+ ...
+ -----> Writing config/database.yml to read from DATABASE_URL
+ -----> Rails plugin injection
+ Injecting rails_log_stdout
+ -----> Discovering process types
+ Procfile declares types -> (none)
+ Default types for Ruby/Rails -> console, rake, web, worker
+
+The buildpack will detect your app as a Rails 2 app if it has a `environment.rb` file in the `config` directory.
+
+#### Rails Log STDOUT
+ A [rails_log_stdout](http://github.com/ddollar/rails_log_stdout) is installed by default so Rails' logger will log to STDOUT and picked up by Heroku's [logplex](http://github.com/heroku/logplex).
+
+#### Auto Injecting Plugins
Any vendored plugin can be stopped from being installed by creating the directory it's installed to in the slug. For instance, to prevent rails_log_stdout plugin from being injected, add `vendor/plugins/rails_log_stdout/.gitkeep` to your git repo.
-## Ruby Language Pack Flow
+### Rails 3
+
+Example Usage:
+
+ $ ls
+ app config config.ru db doc Gemfile Gemfile.lock lib log Procfile public Rakefile README script tmp vendor
+
+ $ ls config/application.rb
+ config/application.rb
+
+ $ heroku create --stack cedar --buildpack http://github.com/heroku/heroku-buildpack-ruby.git
+
+ $ git push heroku master
+ -----> Heroku receiving push
+ -----> Ruby/Rails app detected
+ -----> Installing dependencies using Bundler version 1.1.rc
+ Running: bundle install --without development:test --path vendor/bundle --deployment
+ ...
+ -----> Writing config/database.yml to read from DATABASE_URL
+ -----> Preparing app for Rails asset pipeline
+ Running: rake assets:precompile
+ -----> Rails plugin injection
+ Injecting rails_log_stdout
+ Injecting rails3_serve_static_assets
+ -----> Discovering process types
+ Procfile declares types -> web
+ Default types for Ruby/Rails -> console, rake, worker
+
+The buildpack will detect your apps as a Rails 3 app if it has an `application.rb` file in the `config` directory.
+
+#### Assets
+
+To enable static assets being served on the dyno, [rails3_serve_static_assets](http://github.com/pedro/rails3_serve_static_assets) is installed by default. If the [execjs gem](http://github.com/sstephenson/execjs) is detected then [node.js](http://github.com/joyent/node) will be vendored. The `assets:precompile` rake task will get run if no `public/manifest.yml` is detected. See [this article](http://devcenter.heroku.com/articles/rails31_heroku_cedar) on how rails 3.1 works on cedar.
-Here's the basic flow of how the language pack works:
+Hacking
+-------
+
+To use this buildpack, fork it on Github. Push up changes to your fork, then create a test app with `--buildpack <your-github-url>` and push to it.
+
+To change the vendored binaries for bundler, [Node.js](http://github.com/joyent/node), and rails plugins, use the rake tasks provided by the `Rakefile`. You'll need an S3-enabled AWS account and a bucket to store your binaries in as well as the [vulcan](http://github.com/ddollar/vulcan) gem to build the binaries on heroku.
+
+For example, you can change the vendored version of Bundler to 1.1.rc.
+
+First you'll need to build a Heroku-compatible version of Node.js:
+
+ $ export AWS_ID=xxx AWS_SECRET=yyy S3_BUCKET=zzz
+ $ s3 create $S3_BUCKET
+ $ rake gem:install[bundler,1.1.rc]
+
+Open `lib/language_pack/ruby.rb` in your editor, and change the following line:
+
+ BUNDLER_VERSION = "1.1.rc"
+
+Open `lib/language_pack/base.rb` in your editor, and change the following line:
+
+ VENDOR_URL = "https://s3.amazonaws.com/zzz"
+
+Commit and push the changes to your buildpack to your Github fork, then push your sample app to Heroku to test. You should see:
+
+ -----> Installing dependencies using Bundler version 1.1.rc
+
+NOTE: You'll need to vendor the plugins, node, bundler, and libyaml by running the rake tasks for the buildpack to work properly.
+
+Flow
+----
+
+Here's the basic flow of how the buildpack works:
Ruby (Gemfile and Gemfile.lock is detected)
@@ -47,12 +164,3 @@ Rails 3 (config/application.rb is detected)
* install rails 3 plugins
* [rails3_server_static_assets](https://github.com/pedro/rails3_serve_static_assets)
-## Usage
-
-Add this language pack to your `LANGUAGE_PACK_URL`.
-
- heroku config:add LANGUAGE_PACK_URL="http://github.com/heroku/language-pack-ruby.git"
-
-## Vendored Libraries
-
-The `Rakefile` consists of tools used to help with vendoring libraries. You'll need the [vulcan](http://github.com/ddollar/vulcan) gem to build binaries on heroku. We also use [Amazon's S3](http://aws.amazon.com/s3/) to store all of our vendored libraries. The rake tasks create tarballs which are referenced by the language pack and unpacked during slug compilation.

0 comments on commit e23113a

Please sign in to comment.