rundoc 0.0.1

data/lib/rundoc/parser.rb

@@ -0,0 +1,53 @@
+module Rundoc
+  class Parser
+    DEFAULT_KEYWORD    = ":::"
+    INDENT_BLOCK       = '(?<before_indent>(^\s*$\n|\A)(^(?:[ ]{4}|\t))(?<indent_contents>.*)(?<after_indent>[^\s].*$\n?(?:(?:^\s*$\n?)*^(?:[ ]{4}|\t).*[^\s].*$\n?)*))'
+    GITHUB_BLOCK       = '^(?<fence>(?<fence_char>~|`){3,})\s*?(?<lang>\w+)?\s*?\n(?<contents>.*?)^\g<fence>\g<fence_char>*\s*?\n'
+    CODEBLOCK_REGEX    = /(#{GITHUB_BLOCK})/m
+    COMMAND_REGEX      = ->(keyword) {
+                             /^#{keyword}(?<tag>(\s|=|-)?)\s*(?<command>(\S)+)\s+(?<statement>.*)$/
+                            }
+
+    attr_reader :contents, :keyword, :stack
+
+    def initialize(contents, options = {})
+      @contents = contents
+      @original = contents.dup
+      @keyword  = options[:keyword] || DEFAULT_KEYWORD
+      @stack    = []
+      partition
+    end
+
+    def to_md
+      result = []
+      @stack.each do |s|
+        if s.respond_to?(:render)
+          result << s.render
+        else
+          result << s
+        end
+      end
+      return result.join("")
+    rescue Exception => e
+      File.open("README.md", "w") do |f|
+        f.write(result.join(""))
+      end
+      raise e
+    end
+
+    # split into [before_code, code, after_code], process code, and re-run until tail is empty
+    def partition
+      until contents.empty?
+        head, code, tail = contents.partition(CODEBLOCK_REGEX)
+        @stack << head                  unless head.empty?
+        unless code.empty?
+          match = code.match(CODEBLOCK_REGEX)
+          @stack << CodeSection.new(match, keyword: keyword)
+        end
+        @contents = tail
+      end
+    end
+  end
+end
+
+# convert string of markdown to array of strings and code_command

data/lib/rundoc/version.rb

@@ -0,0 +1,3 @@
+module Rundoc
+  VERSION = "0.0.1"
+end

data/rundoc.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rundoc/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "rundoc"
+  gem.version       = Rundoc::VERSION
+  gem.authors       = ["Richard Schneeman"]
+  gem.email         = ["richard.schneeman+rubygems@gmail.com"]
+  gem.description   = %q{rundoc turns docs to runable code}
+  gem.summary       = %q{rundoc generates runable code from docs}
+  gem.homepage      = "https://github.com/schneems/rundoc"
+  gem.license       = "MIT"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+
+  gem.add_dependency "thor"
+  gem.add_dependency "repl_runner"
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "mocha"
+end
+

data/test/fixtures/play/source.md

@@ -0,0 +1,231 @@
+```
+:::- rundoc
+Rundoc.configure do |config|
+  config.project_root = "myapp"
+end
+```
+
+This quickstart will get you going with a Java and Play Framework application that uses a WebSocket, deployed to Heroku. For general information on how to develop and architect apps for use on Heroku, see [Architecting Applications for Heroku](https://devcenter.heroku.com/articles/architecting-apps).
+
+>note
+> Sample code for the [demo application](https://github.com/heroku/play-ws-test) is available on GitHub. Edits and enhancements are welcome. Just fork the repository, make your changes and send us a pull request.
+
+## Prerequisites
+
+* Java, Play Framework 2.x, Git, and the Heroku client (as described in the [basic Java quickstart](java))
+* A Heroku user account.  [Signup is free and instant](https://api.heroku.com/signup/devcenter).
+
+## Create a Play Framework Java app that uses a WebSocket
+
+The sample application provides a simple example of using a WebSocket with Java and Play. You can clone the sample and follow along with the code as you read. If you'd rather write the app yourself you can add the sample code to a new Play app as you go.
+
+### Option 1. Clone the sample app
+
+If you want to get going more quickly you can just clone the sample app:
+
+```term
+$ git clone git@github.com:heroku/play-ws-test.git
+Cloning into 'play-ws-test'...
+remote: Counting objects: 31, done.
+remote: Compressing objects: 100% (24/24), done.
+remote: Total 31 (delta 0), reused 31 (delta 0)
+Receiving objects: 100% (31/31), 38.33 KiB | 0 bytes/s, done.
+Checking connectivity... done
+```
+
+### Option 2. Create a new Play app
+
+```term
+:::- $ play help
+:::= $ play new myapp
+mywebsocketapp
+2
+
+:::= $ cd myapp
+```
+
+Choose an application name and Java as the language.
+
+## The sample application
+
+The sample application renders a simple web page that will open a WebSocket to the backend. The server will send a payload containing the time over the WebSocket once a second. That time will be displayed on the page.
+
+There are 3 important pieces to the interaction that takes place here: a controller method that returns a WebSocket object, a JavaScript method that opens that WebSocket, and an Akka actor that sends the payload across that WebSocket every second. Let's explore each.
+
+### Returning a WebSocket from a controller method
+
+You can [return a WebSocket](http://www.playframework.com/documentation/2.2.x/JavaWebSockets) from a Play controller method.
+
+There is an example in `Application.java` in the sample application:
+
+```java
+:::= write app/controllers/Application.java
+package controllers;
+
+import static java.util.concurrent.TimeUnit.SECONDS;
+import models.Pinger;
+import play.libs.Akka;
+import play.libs.F.Callback0;
+import play.mvc.Controller;
+import play.mvc.Result;
+import play.mvc.WebSocket;
+import scala.concurrent.duration.Duration;
+import views.html.index;
+import akka.actor.ActorRef;
+import akka.actor.Cancellable;
+import akka.actor.Props;
+
+public class Application extends Controller {
+    public static WebSocket<String> pingWs() {
+        return new WebSocket<String>() {
+            public void onReady(WebSocket.In<String> in, WebSocket.Out<String> out) {
+                final ActorRef pingActor = Akka.system().actorOf(Props.create(Pinger.class, in, out));
+                final Cancellable cancellable = Akka.system().scheduler().schedule(Duration.create(1, SECONDS),
+                                                   Duration.create(1, SECONDS),
+                                                   pingActor,
+                                                   "Tick",
+                                                   Akka.system().dispatcher(),
+                                                   null
+                                                   );
+
+                in.onClose(new Callback0() {
+                  @Override
+                  public void invoke() throws Throwable {
+                    cancellable.cancel();
+                  }
+                });
+            }
+
+        };
+    }
+
+    public static Result pingJs() {
+        return ok(views.js.ping.render());
+    }
+
+    public static Result index() {
+        return ok(index.render());
+    }
+}
+```
+
+This method returns a new [WebSocket](http://www.playframework.com/documentation/2.0/api/java/play/mvc/WebSocket.html) object that has a String as its payload. In the WebSocket object we define the onReady method to talk to an actor via the Akka scheduler. The work of sending data over the socket will occur in that actor.
+
+The other methods will render our `js` and `html` templates.
+
+
+We'll also need a route to be set up for these methods in our `routes` file:
+
+```
+:::= write conf/routes
+# Home page
+GET     /                           controllers.Application.index()
+GET     /pingWs                     controllers.Application.pingWs()
+GET     /assets/javascripts/ping.js controllers.Application.pingJs()
+
+# Map static resources from the /public folder to the /assets URL path
+GET     /assets/*file               controllers.Assets.at(path="/public", file)
+```
+
+### Sending data over a WebSocket
+
+In the controller example you'll notice that we pass around the `in` and `out` streams of the WebSocket. In our actor we're able to read from and write to these streams just like any other IO stream. Here's the code for the `Pinger` actor:
+
+```java
+:::= write app/models/Pinger.java
+package models;
+
+import play.*;
+import play.mvc.*;
+import play.libs.*;
+
+import scala.concurrent.duration.Duration;
+import java.util.concurrent.TimeUnit;
+import akka.actor.UntypedActor;
+import java.util.Calendar;
+import java.text.SimpleDateFormat;
+
+public class Pinger extends UntypedActor {
+    WebSocket.In<String> in;
+    WebSocket.Out<String> out;
+
+    public Pinger(WebSocket.In<String> in, WebSocket.Out<String> out) {
+        this.in = in;
+        this.out = out;
+    }
+
+    @Override
+    public void onReceive(Object message) {
+        if (message.equals("Tick")) {
+            SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
+            Calendar cal = Calendar.getInstance();
+            out.write(sdf.format(cal.getTime()));
+        } else {
+            unhandled(message);
+        }
+    }
+}
+```
+
+You'll notice that this actor counts on the schedule defined in the controller method to send it a "Tick" message every second. When that happens it sends the current date and time over the WebSocket.
+
+### Connecting to a WebSocket
+
+The final piece is the client code that will call the WebSocket. For this our sample application uses Scala js and HTML templates called `ping.scala.js` and `index.scala.js` respectively.
+
+`index.scala.js` provides a `div` to display the data in and references the JavaScript:
+
+```java
+:::= write app/views/index.scala.html
+@main("Welcome to Play") {
+
+    <strong>Stats</strong><br>
+    <div id="ping"></div>
+
+   <script type="text/javascript" charset="utf-8" src="@routes.Application.pingJs()"></script>
+}
+```
+
+`ping.scala.js` connects to our WebSocket and defines the `receiveEvent` method to populate the dates into the displayed `div` as they come across:
+
+```javascript
+:::= write app/views/ping.scala.js
+$(function() {
+    var WS = window['MozWebSocket'] ? MozWebSocket : WebSocket
+    var dateSocket = new WS("@routes.Application.pingWs().webSocketURL(request)")
+
+    var receiveEvent = function(event) {
+        $("#ping").html("Last ping: "+event.data);
+    }
+
+    dateSocket.onmessage = receiveEvent
+})
+```
+
+## Deploy the application to Heroku
+
+### Store your app in Git
+
+If you haven't done so already put your application into a git repository:
+
+```term
+:::= $ git init
+:::= $ git add .
+:::= $ git commit -m "Ready to deploy"
+```
+
+### Create the app
+
+```term
+#:::= $ heroku create
+```
+
+### Deploy your code
+
+```term
+#:::= $ git push heroku master
+#:::- $ heroku labs:enable websockets
+#:::- $ heroku restart
+```
+
+Congratulations! Your web app should now be up and running on Heroku.

data/test/fixtures/rails_4/rundoc.md

@@ -0,0 +1,504 @@
+```
+:::- rundoc
+email = ENV['HEROKU_EMAIL'] || `heroku auth:whoami`
+
+Rundoc.configure do |config|
+  config.project_root = "myapp"
+  config.filter_sensitive(email, "developer@example.com")
+end
+```
+
+Ruby on Rails is a popular web framework written in [Ruby](http://www.ruby-lang.org/). This guide covers using Rails 4 on Heroku, running previous versions of Rails on Heroku see [Getting Started with Rails 3.x on Heroku](https://devcenter.heroku.com/articles/rails3).
+
+> callout If you are already familiar with Heroku and Rails, reference the [simplifed Rails 4 on Heroku guide](https://devcenter.heroku.com/articles/rails4) instead. For general information on how to develop and architect apps for use on Heroku, see [Architecting Applications for Heroku](https://devcenter.heroku.com/articles/architecting-apps).
+
+For this guide you will need:
+
+- Basic Ruby/Rails knowledge
+- Locally installed version of Ruby 2.0.0+, Rubygems, Bundler, and Rails 4+
+- Basic Git knowledge
+- A Heroku user account: [Signup is free and instant](https://api.heroku.com/signup/devcenter)
+
+## Local Workstation Setup
+
+Install the [Heroku Toolbelt](https://toolbelt.heroku.com/) on your local workstation. This ensures that you have access to the [Heroku command-line client](/categories/command-line), Foreman, and the Git revision control system. You will also need [Ruby and Rails installed](http://guides.railsgirls.com/install/).
+
+Once installed, you'll have access to the `$ heroku` command from your command shell. Log in using the email address and password you used when creating your Heroku account:
+
+
+> callout Note that `$` symbol before commands indicates they should be run on the command line, prompt, or terminal with appropriate permissions. Do not copy the `$` symbol.
+
+```sh
+$ heroku login
+Enter your Heroku credentials.
+Email: schneems@example.com
+Password:
+Could not find an existing public key.
+Would you like to generate one? [Yn]
+Generating new SSH public key.
+Uploading ssh public key /Users/adam/.ssh/id_rsa.pub
+```
+
+Press enter at the prompt to upload your existing `ssh` key or create a new one, used for pushing code later on.
+
+## Write your App
+
+> callout To run on Heroku your app must be configured to use the Postgres database, have all dependencies declared in your `Gemfile`, and have the `rails_12factor` gem in the production group of your `Gemfile`
+
+
+You may be starting from an existing app, if so [upgrade to Rails 4](http://edgeguides.rubyonrails.org/upgrading_ruby_on_rails.html#upgrading-from-rails-3-2-to-rails-4-0) before continuing. If not, a vanilla Rails 4 app will serve as a suitable sample app. To build a new app make sure that you're using the Rails 4.x using `$ rails -v`. You can get the new version of rails by running,
+
+```sh
+:::= $ gem install rails --no-ri --no-rdoc
+```
+
+Then create a new app:
+
+```sh
+::: $ rails new myapp --database=postgresql
+```
+
+Once finished change your directory to the newly created Rails app
+
+```sh
+::: $ cd myapp
+```
+
+> callout If you experience problems or get stuck with this tutorial, your questions may be answered in a later part of this document. Once you experience a problem try reading through the entire document and then going back to your issue. It can also be useful to review your previous steps to ensure they all executed correctly.
+
+Rails 4 no longer has a static index page in production. When you're using a new app, there will not be a root page in production, so we need to create one. We will first create a controller called `welcome` for our home page to live:
+
+```sh
+::: $ rails generate controller welcome
+```
+
+Next we'll add an index page.
+
+```sh
+:::= file.write app/views/welcome/index.html.erb
+<h2>Hello World</h2>
+<p>
+  The time is now: <%= Time.now %>
+</p>
+```
+
+Now we need to have Rails route to this action. We'll edit `config/routes.rb` to set the index page to our new method:
+
+```ruby
+:::= file.append config/routes.rb#2
+  root 'welcome#index'
+```
+
+You can verify that the page is there by running your server:
+
+```sh
+$ rails server
+```
+
+And visiting [http://localhost:3000](http://localhost:3000) in your browser. If you do not see the page, use the logs that are output to your server to debug.
+
+## Heroku gems
+
+Heroku integration has previously relied on using the Rails plugin system, which has been removed from Rails 4. To enable features such as static asset serving and logging on Heroku please add `rails_12factor` gem to your `Gemfile`.
+
+```ruby
+:::= file.append Gemfile
+gem 'rails_12factor', group: :production
+```
+
+Then run:
+
+```sh
+::: $ bundle install
+```
+
+We talk more about Rails integration on our [Ruby Support page](https://devcenter.heroku.com/articles/ruby-support#injected-plugins).
+
+## Use Postgres
+
+> callout We highly recommend using PostgreSQL during development. Maintaining [parity between your development](http://www.12factor.net/dev-prod-parity) and deployment environments prevents subtle bugs from being introduced because of differences between your environments. [Install Postgres locally](https://devcenter.heroku.com/articles/heroku-postgresql#local-setup) now if it is not allready on your system.
+
+If you did not specify `postgresql` while creating your app (using `--database=postgresql`) you will need to add the `pg` gem to your Rails project. Edit your `Gemfile` and change this line:
+
+```ruby
+gem 'sqlite3'
+```
+
+To this:
+
+```ruby
+gem 'pg'
+```
+
+You can get more information on why this change is needed and how to configure your app to run postgres locally see [why you cannot use Sqlite3 on Heroku](https://devcenter.heroku.com/articles/sqlite3).
+
+In addition to using the `pg` gem, you'll also need to ensure the `config/database.yml` is using the `postgresql` adapter.
+
+You will also need to remove the `username` field in your `database.yml` if there is one so:
+
+```
+:::= file.remove config/database.yml
+username: myapp
+```
+
+This line tells rails that the database `myapp_development` should be run under a role of `myapp`. Since you likely don't have this role in your database we will remove it. With the line remove Rails will try to access the database as user who is currently logged into the computer.
+
+The development section of your `config/database.yml` file should look something like this:
+
+```sh
+:::  $ cat config/database.yml
+:::= | $ head -n 23
+```
+
+Be careful here, if you omit the `sql` at the end of `postgresql` your application will not work.
+
+Now re-install your dependencies (to generate a new `Gemfile.lock`):
+
+```ruby
+$ bundle install
+```
+
+## Specify Ruby version in app
+
+
+Rails 4 requires Ruby 1.9.3 or above. Heroku has a recent version of Ruby installed, however you can specify an exact version by using the `ruby` DSL in your `Gemfile`. For this guide we'll be using Ruby 2.0.0 so add this to your `Gemfile`:
+
+```ruby
+:::= file.append Gemfile
+ruby "2.0.0"
+```
+
+You should also be running the same version of Ruby locally. You can verify by running `$ ruby -v`. You can get more information on [specifying your Ruby version on Heroku here](https://devcenter.heroku.com/articles/ruby-versions).
+
+## Store your App in Git
+
+Heroku relies on [git](http://git-scm.com/), a distributed source control managment tool, for deploying your project. If your project is not already in git first verify that `git` is on your system:
+
+```sh
+::: $ git --help
+:::= | $ head -n 10
+```
+
+If you don't see any output or get `command not found` you will need to install it on your system, verify that the [Heroku toolbelt](https://toolbelt.heroku.com/) is installed.
+
+Once you've verified that git works, first make sure you are in your Rails app directory by running:
+
+```sh
+$ ls
+```
+
+The output should look like this:
+
+```sh
+:::= $ ls
+```
+
+Now run these commands in your Rails app directory to initialize and commit your code to git:
+
+```sh
+::: $ git init
+::: $ git add .
+::: $ git commit -m "init"
+```
+
+You can verify everything was committed correctly by running:
+
+```sh
+:::= $ git status
+```
+
+Now that your application is committed to git you can deploy to Heroku.
+
+## Deploy your application to Heroku
+
+Make sure you are in the directory that contains your Rails app, then create an app on Heroku:
+
+```sh
+:::= $ heroku create
+```
+
+You can verify that the remote was added to your project by running
+
+```sh
+$ git config -e
+```
+
+If you see `fatal: not in a git directory` then you are likely not in the corect directory. Otherwise you may deploy your code. After you deploy your code, you will need to migrate your database, make sure it is properly scaled and use logs to debug any issues that come up.
+
+Deploy your code:
+
+```sh
+:::= $ git push heroku master
+```
+
+It is always a good idea to check to see if there are any warnings or errors in the output. If everything went well you can migrate your database.
+
+## Migrate your database
+
+If you are using the database in your application you need to manually migrate the database by running:
+
+```sh
+$ heroku run rake db:migrate
+```
+
+Any commands after the `heroku run` will be executed on a Heroku [dyno](dynos).
+
+
+## Visit your application
+
+
+You've deployed your code to Heroku. You can now instruct Heroku to execute a process type. Heroku does this by running the associated command in a [dyno](dynos) - a lightweight container which is the basic unit of composition on Heroku.
+
+Let's ensure we have one dyno running the `web` process type:
+
+```sh
+::: $ heroku ps:scale web=1
+```
+
+You can check the state of the app's dynos. The `heroku ps` command lists the running dynos of your application:
+
+```sh
+:::= $ heroku ps
+```
+
+Here, one dyno is running.
+
+We can now visit the app in our browser with `heroku open`.
+
+```sh
+:::= $ heroku open
+```
+
+You should now see the "Hello World" text we inserted above.
+
+Heroku gives you a default web url for simplicty while you are developing. When you are ready to scale up and use Heroku for production you can add your own [Custom Domain](https://devcenter.heroku.com/articles/custom-domains).
+
+## View the logs
+
+If you run into any problems getting your app to perform properly, you will need to check the logs.
+
+You can view information about your running app using one of the [logging commands](logging), `heroku logs`:
+
+```sh
+:::= $ heroku logs
+```
+
+You can also get the full stream of logs by running the logs command with the `--tail` flag option like this:
+
+```sh
+$ heroku logs --tail
+```
+
+## Dyno sleeping and scaling
+
+Having only a single web dyno running will result in the dyno [going to sleep](dynos#dyno-sleeping) after one hour of inactivity.  This causes a delay of a few seconds for the first request upon waking. Subsequent requests will perform normally.
+
+To avoid this, you can scale to more than one web dyno. For example:
+
+```sh
+$ heroku ps:scale web=2
+```
+
+For each application, Heroku provides [750 free dyno-hours](usage-and-billing#750-free-dyno-hours-per-app).  Running your app at 2 dynos would exceed this free, monthly allowance, so let's scale back:
+
+```sh
+$ heroku ps:scale web=1
+```
+
+## Console
+
+Heroku allows you to run commands in a [one-off dyno](oneoff-admin-ps) - scripts and applications that only need to be executed when needed - using the `heroku run` command. Use this to launch a Rails console process attached to your local terminal for experimenting in your app's environment:
+
+```sh
+$ heroku run rails console
+irb(main):001:0> puts 1+1
+2
+```
+
+## Rake
+
+Rake can be run as an attached process exactly like the console:
+
+```sh
+$ heroku run rake db:migrate
+```
+
+## Webserver
+
+By default, your app's web process runs `rails server`, which uses Webrick. This is fine for testing, but for production apps you'll want to switch to a more robust webserver. On Cedar, [we recommend Unicorn as the webserver](ruby-production-web-server). Regardless of the webserver you choose, production apps should always specify the webserver explicitly in the `Procfile`.
+
+First, add Unicorn to your application `Gemfile`:
+
+```ruby
+:::= file.append Gemfile
+gem 'unicorn'
+```
+
+Then run
+
+```sh
+::: $ bundle install
+```
+
+Now you are ready to configure your app to use Unicorn.
+
+Create a configuration file for Unicorn at `config/unicorn.rb`:
+
+```sh
+::: $ touch config/unicorn.rb
+```
+
+Now we're going to add Unicorn specific configuration options, that we explain in detail in [Heroku's Unicorn documentation](https://devcenter.heroku.com/articles/rails-unicorn):
+
+```ruby
+:::= file.write config/unicorn.rb
+
+worker_processes Integer(ENV["WEB_CONCURRENCY"] || 3)
+timeout 15
+preload_app true
+
+before_fork do |server, worker|
+  Signal.trap 'TERM' do
+    puts 'Unicorn master intercepting TERM and sending myself QUIT instead'
+    Process.kill 'QUIT', Process.pid
+  end
+
+  defined?(ActiveRecord::Base) and
+    ActiveRecord::Base.connection.disconnect!
+end
+
+after_fork do |server, worker|
+  Signal.trap 'TERM' do
+    puts 'Unicorn worker intercepting TERM and doing nothing. Wait for master to send QUIT'
+  end
+
+  defined?(ActiveRecord::Base) and
+    ActiveRecord::Base.establish_connection
+end
+```
+
+This default configuration assumes a standard Rails app with Active Record. You should get acquainted with the different options in [the official Unicorn documentation](http://unicorn.bogomips.org/Unicorn/Configurator.html).
+
+Finally you will need to tell Heroku how to run your Rails app by creating a `Procfile` in the root of your application directory.
+
+### Procfile
+
+Change the command used to launch your web process by creating a file called [Procfile](procfile) and entering this:
+
+```
+:::= file.write Procfile
+web: bundle exec unicorn -p $PORT -c ./config/unicorn.rb
+```
+
+Note: The case of `Procfile` matters, the first letter must be uppercase.
+
+Set the `RACK_ENV` to development in your environment and a `PORT` to connect to. Before pushing to Heroku you'll want to test with the `RACK_ENV` set to production since this is the enviroment your Heroku app will run in.
+
+```sh
+:::= $ echo "RACK_ENV=development" >>.env
+:::= $ echo "PORT=3000" >> .env
+```
+
+You'll also want to add `.env` to your `.gitignore` since this is for local enviroment setup.
+
+```sh
+::: $ echo ".env" >> .gitignore
+::: $ git add .gitignore
+::: $ git commit -m "add .env to .gitignore"
+```
+
+Test your Procfile locally using Foreman:
+
+```sh
+::: $ gem install foreman
+```
+
+You can now start your web server by running
+
+```sh
+$ foreman start
+18:24:56 web.1  | I, [2013-03-13T18:24:56.885046 #18793]  INFO -- : listening on addr=0.0.0.0:5000 fd=7
+18:24:56 web.1  | I, [2013-03-13T18:24:56.885140 #18793]  INFO -- : worker=0 spawning...
+18:24:56 web.1  | I, [2013-03-13T18:24:56.885680 #18793]  INFO -- : master process ready
+18:24:56 web.1  | I, [2013-03-13T18:24:56.886145 #18795]  INFO -- : worker=0 spawned pid=18795
+18:24:56 web.1  | I, [2013-03-13T18:24:56.886272 #18795]  INFO -- : Refreshing Gem list
+18:24:57 web.1  | I, [2013-03-13T18:24:57.647574 #18795]  INFO -- : worker=0 ready
+```
+
+Looks good, so press Ctrl-C to exit and you can deploy your changes to Heroku:
+
+```sh
+::: $ git add .
+::: $ git commit -m "use unicorn via procfile"
+::: $ git push heroku master
+```
+
+Check `ps`, you'll see the web process uses your new command specifying Unicorn as the web server
+
+```sh
+:::= $ heroku ps
+```
+
+The logs also reflect that we are now using Unicorn:
+
+```sh
+$ heroku logs
+```
+
+## Rails Asset Pipeline
+
+There are several options for invoking the [Rails asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) when deploying to Heroku. For general information on the asset pipeline please see the [Rails 3.1+ Asset Pipeline on Heroku Cedar](rails3x-asset-pipeline-cedar) article.
+
+The `config.assets.initialize_on_precompile` option has been removed is and not needed for Rails 4. Also, any failure in asset compilation will now cause the push to fail. For Rails 4 asset pipeline support see the [Ruby Support](https://devcenter.heroku.com/articles/ruby-support#rails-4-x-applications) page.
+
+## Troubleshooting
+
+If you push up your app and it crashes (`heroku ps` shows state `crashed`), check your logs to find out what went wrong. Here are some common problems.
+
+### Runtime dependencies on development/test gems
+
+If you're missing a gem when you deploy, check your Bundler groups. Heroku builds your app without the `development` or `test` groups, and if you app depends on a gem from one of these groups to run, you should move it out of the group.
+
+One common example using the RSpec tasks in your `Rakefile`. If you see this in your Heroku deploy:
+
+```sh
+$ heroku run rake -T
+Running `bundle exec rake -T` attached to terminal... up, ps.3
+rake aborted!
+no such file to load -- rspec/core/rake_task
+```
+
+Then you've hit this problem. First, duplicate the problem locally:
+
+```sh
+$ bundle install --without development:test
+…
+$ bundle exec rake -T
+rake aborted!
+no such file to load -- rspec/core/rake_task
+```
+
+Now you can fix it by making these Rake tasks conditional on the gem load. For example:
+
+### Rakefile
+
+```ruby
+begin
+  require "rspec/core/rake_task"
+
+  desc "Run all examples"
+
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.rspec_opts = %w[--color]
+    t.pattern = 'spec/**/*_spec.rb'
+  end
+rescue LoadError
+end
+```
+
+Confirm it works locally, then push to Heroku.
+
+
+## Done
+
+You now have your first application deployed to Heroku. The next step is to deploy your own application. If you're interested in reading more you can read more about [Ruby on Heroku at the Devcenter](https://devcenter.heroku.com/categories/ruby).