Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 193 lines (131 sloc) 7.497 kb
e23113a @hone update readme to new style
hone authored
1 Heroku buildpack: Ruby
2 ======================
9446500 @hone initial readme
hone authored
3
83b14d1 @oguzbilgic Fix heroku link on README
oguzbilgic authored
4 This is a [Heroku buildpack](http://devcenter.heroku.com/articles/buildpacks) for Ruby, Rack, and Rails apps. It uses [Bundler](http://gembundler.com) for dependency management.
9446500 @hone initial readme
hone authored
5
e23113a @hone update readme to new style
hone authored
6 Usage
7 -----
9446500 @hone initial readme
hone authored
8
e23113a @hone update readme to new style
hone authored
9 ### Ruby
9446500 @hone initial readme
hone authored
10
e23113a @hone update readme to new style
hone authored
11 Example Usage:
9446500 @hone initial readme
hone authored
12
e23113a @hone update readme to new style
hone authored
13 $ ls
14 Gemfile Gemfile.lock
9446500 @hone initial readme
hone authored
15
6157037 @catsby Update README.md
catsby authored
16 $ heroku create --stack cedar --buildpack https://github.com/heroku/heroku-buildpack-ruby.git
9446500 @hone initial readme
hone authored
17
e23113a @hone update readme to new style
hone authored
18 $ git push heroku master
19 ...
20 -----> Heroku receiving push
21 -----> Fetching custom buildpack
22 -----> Ruby app detected
23 -----> Installing dependencies using Bundler version 1.1.rc
24 Running: bundle install --without development:test --path vendor/bundle --deployment
25 Fetching gem metadata from http://rubygems.org/..
26 Installing rack (1.3.5)
27 Using bundler (1.1.rc)
28 Your bundle is complete! It was installed into ./vendor/bundle
29 Cleaning up the bundler cache.
30 -----> Discovering process types
31 Procfile declares types -> (none)
32 Default types for Ruby -> console, rake
9446500 @hone initial readme
hone authored
33
b16333e @hone capitalize all instances of Bundler that aren't commands
hone authored
34 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).
e23113a @hone update readme to new style
hone authored
35
1ae626f @schneems add testing docs to the README
schneems authored
36 #### Run the Tests
37
5df432d @schneems Parallel tests
schneems authored
38 The tests on this buildpack are written in Rspec to allow the use of
39 `focused: true`. Parallelization of testing is provided by
40 https://github.com/grosser/parallel_tests this lib spins up an arbitrary
41 number of processes and running a different test file in each process,
42 it does not parallelize tests within a test file. To run the tests: clone the repo, then `bundle install` then clone the test fixtures by running:
1ae626f @schneems add testing docs to the README
schneems authored
43
44 ```sh
45 $ hatchet install
46 ```
47
48 Now run the tests:
49
50 ```sh
5df432d @schneems Parallel tests
schneems authored
51 $ bundle exec parallel_rspec -n 6 spec/
52 ```
53
54 If you don't want to run them in parallel you can still:
55
56 ```sh
57 $ bundle exec rake spec
1ae626f @schneems add testing docs to the README
schneems authored
58 ```
59
60 Now go take a nap or something for a really long time.
61
e23113a @hone update readme to new style
hone authored
62 #### Bundler
63
b16333e @hone capitalize all instances of Bundler that aren't commands
hone authored
64 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.
e23113a @hone update readme to new style
hone authored
65
66 ### Rails 2
67
68 Example Usage:
69
70 $ ls
71 app config db doc Gemfile Gemfile.lock lib log public Rakefile README script test tmp vendor
72
73 $ ls config/environment.rb
74 config/environment.rb
75
6157037 @catsby Update README.md
catsby authored
76 $ heroku create --stack cedar --buildpack https://github.com/heroku/heroku-buildpack-ruby.git
e23113a @hone update readme to new style
hone authored
77
78 $ git push heroku master
79 ...
80 -----> Heroku receiving push
81 -----> Ruby/Rails app detected
82 -----> Installing dependencies using Bundler version 1.1.rc
83 ...
84 -----> Writing config/database.yml to read from DATABASE_URL
85 -----> Rails plugin injection
86 Injecting rails_log_stdout
87 -----> Discovering process types
88 Procfile declares types -> (none)
89 Default types for Ruby/Rails -> console, rake, web, worker
90
91 The buildpack will detect your app as a Rails 2 app if it has a `environment.rb` file in the `config` directory.
92
93 #### Rails Log STDOUT
94 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).
95
96 #### Auto Injecting Plugins
9446500 @hone initial readme
hone authored
97
98 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.
b3d2688 @hone add flow to readme
hone authored
99
e23113a @hone update readme to new style
hone authored
100 ### Rails 3
101
102 Example Usage:
103
104 $ ls
105 app config config.ru db doc Gemfile Gemfile.lock lib log Procfile public Rakefile README script tmp vendor
106
107 $ ls config/application.rb
108 config/application.rb
109
6157037 @catsby Update README.md
catsby authored
110 $ heroku create --stack cedar --buildpack https://github.com/heroku/heroku-buildpack-ruby.git
e23113a @hone update readme to new style
hone authored
111
112 $ git push heroku master
113 -----> Heroku receiving push
114 -----> Ruby/Rails app detected
115 -----> Installing dependencies using Bundler version 1.1.rc
116 Running: bundle install --without development:test --path vendor/bundle --deployment
117 ...
118 -----> Writing config/database.yml to read from DATABASE_URL
119 -----> Preparing app for Rails asset pipeline
120 Running: rake assets:precompile
121 -----> Rails plugin injection
122 Injecting rails_log_stdout
123 Injecting rails3_serve_static_assets
124 -----> Discovering process types
125 Procfile declares types -> web
126 Default types for Ruby/Rails -> console, rake, worker
127
128 The buildpack will detect your apps as a Rails 3 app if it has an `application.rb` file in the `config` directory.
129
130 #### Assets
131
132 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.
b3d2688 @hone add flow to readme
hone authored
133
e23113a @hone update readme to new style
hone authored
134 Hacking
135 -------
136
137 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.
138
bbd5ff2 @sumbach Update link to vulcan gem
sumbach authored
139 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/heroku/vulcan) gem to build the binaries on heroku.
e23113a @hone update readme to new style
hone authored
140
141 For example, you can change the vendored version of Bundler to 1.1.rc.
142
143 First you'll need to build a Heroku-compatible version of Node.js:
144
145 $ export AWS_ID=xxx AWS_SECRET=yyy S3_BUCKET=zzz
146 $ s3 create $S3_BUCKET
147 $ rake gem:install[bundler,1.1.rc]
148
149 Open `lib/language_pack/ruby.rb` in your editor, and change the following line:
150
151 BUNDLER_VERSION = "1.1.rc"
152
153 Open `lib/language_pack/base.rb` in your editor, and change the following line:
154
155 VENDOR_URL = "https://s3.amazonaws.com/zzz"
156
157 Commit and push the changes to your buildpack to your Github fork, then push your sample app to Heroku to test. You should see:
158
159 -----> Installing dependencies using Bundler version 1.1.rc
160
b16333e @hone capitalize all instances of Bundler that aren't commands
hone authored
161 NOTE: You'll need to vendor the plugins, node, Bundler, and libyaml by running the rake tasks for the buildpack to work properly.
e23113a @hone update readme to new style
hone authored
162
163 Flow
164 ----
165
166 Here's the basic flow of how the buildpack works:
b3d2688 @hone add flow to readme
hone authored
167
168 Ruby (Gemfile and Gemfile.lock is detected)
169
b16333e @hone capitalize all instances of Bundler that aren't commands
hone authored
170 * runs Bundler
b3d2688 @hone add flow to readme
hone authored
171 * installs binaries
04788ac @hone update readme
hone authored
172 * installs node if the gem execjs is detected
88b676e @hone update readme
hone authored
173 * runs `rake assets:precompile` if the rake task is detected
b3d2688 @hone add flow to readme
hone authored
174
2356972 @hone add section on rack
hone authored
175 Rack (config.ru is detected)
b3d2688 @hone add flow to readme
hone authored
176
177 * everything from Ruby
2356972 @hone add section on rack
hone authored
178 * sets RACK_ENV=production
179
180 Rails 2 (config/environment.rb is detected)
181
182 * everything from Rack
be605ae @hone show that rails 2 sets RAILS_ENV
hone authored
183 * sets RAILS_ENV=production
b3d2688 @hone add flow to readme
hone authored
184 * install rails 2 plugins
185 * [rails_log_stdout](http://github.com/ddollar/rails_log_stdout)
186
187 Rails 3 (config/application.rb is detected)
188
189 * everything from Rails 2
190 * install rails 3 plugins
191 * [rails3_server_static_assets](https://github.com/pedro/rails3_serve_static_assets)
662cc92 @hone add usage section to README
hone authored
192
Something went wrong with that request. Please try again.