Heroku Cookbook

Let's go to www.heroku.com and create an account if we do not already have one.

Next, let's install the Heroku Toolbelt. Specific download and installation instructions are available at https://toolbelt.heroku.com/ for Mac, Windows, and Linux.

Once the Heroku Toolbelt is installed, we can verify that everything is working by opening up a terminal and running the following command:

$ heroku --version
heroku-toolbelt/3.11.1 (x86_64-darwin10.8.0) ruby/1.9.3

We should see the version of the Heroku Toolbelt we are using printed to the console.

Let's log in by opening up a terminal and running the following command:

$ heroku login
Username: youremail@example.com
Password (typing will be hidden):
Could not find an existing public key.Would you like to generate one? [Yn]Generating new SSH public key.Uploading ssh public key /Users/mc/.ssh/id_rsa.pub

If we do not have an existing public key, the Heroku CLI will provide us with instructions on how to create one here. This key will be uploaded to Heroku's servers and used for authentication whenever we push new code to our applications.

We can ensure that we are authenticated with the auth:whoami command. If logged in successfully, it will print our e-mail address:

$ heroku auth:whoami
youremail@example.com

Finally, we should go to the Heroku dashboard and verify our account by adding a credit card. Having a verified account will allow us to scale our applications and install add-ons (https://dashboard.heroku.com/account).

If we've never used Git before, we'll want to tell it our name and e-mail. These will be used to identify us as the author in all our commits:

$ git config --global user.name 'First and Last name here' 
$ git config --global user.email 'yourname@example.com'

Now, let's create a new directory to practice with:

$ mkdir LearningGit
$ cd LearningGit

In our new directory, we'll need to initialize a new Git repository:

$ git init
Initialized empty Git repository in /home/mc/LearningGit/.git/

Now, let's create a new file in our project using touch:

$ touch new_file.txt

We can use the status command to check whether this file is currently untracked by Git:

$ git status
On branch master

Initial commit

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        new_file.txt

nothing added to commit but untracked files present (use "git add" to track)

We need to explicitly tell Git to track the file using the add command:

$ git add new_file.txt

Our file is now created and being tracked by Git, but it is not yet committed to our repository's history. Let's commit it now:

$ git commit -m "Adding new_file to Git"
[master (root-commit) b79ca0b] Adding new_file to Git
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 LearningGit/new_file.txt

To view the history of our Git repository, we can use the log command. Use the q key to escape from viewing logs. Use the arrow keys to scroll:

$ git log
commit b79ca0b7c7671789cc8359fe43e1144af835c2d1
Author: Mike Coutermarsh <coutermarsh.mike@gmail.com>
Date:   Mon Mar 3 20:31:47 2014 -0500

Adding new_file to Git

One of the easiest ways to install Ruby is to use Ruby Version Manager (RVM). We can find the latest installation instructions for RVM at http://rvm.io/rvm/install.

Once RVM is installed, we can run the following command in a terminal to install Ruby 2.1.3:

$ rvm install 2.1.3

We'll use Bundler to manage and install our applications' dependencies. Let's make sure we have the latest version installed by running the following command:

$ gem install bundler

This application also uses a Postgres database. We'll be using Postgres frequently throughout the book; if we do not have it installed on our machine, now is a good time to get it set up:

First, we need to download the source code for our sample app from GitHub. We can do this using git clone:

$ git clone https://github.com/mscoutermarsh/refinery_heroku.git

Now, let's navigate to our new directory and create a new Heroku app. Creating a new app will also add a new heroku remote to our Git repository. This remote is where we will be soon pushing our code for deployment:

$ cd refinery_heroku
$ heroku apps:create
  Creating cryptic-chamber-6830... done, stack is cedar
  http://cryptic-chamber-6830.herokuapp.com/ | git@heroku.com:cryptic-chamber-6830.git
  Git remote heroku added

We will tell Heroku how to run our app with a Procfile. In the root directory of our new app, we'll create a new Procfile to tell Heroku how to start up our web service. Let's create the file using the touch command:

$ touch Procfile

Now, let's open our new Procfile and add the following line. This will tell Heroku how to start our web server process:

web: bundle exec unicorn -p $PORT -c ./config/unicorn.rb

We can now commit these changes to Git:

$ git add Procfile
$ git commit -m 'Adding Procfile for Heroku'

Next, let's add the Twelve-Factor app gem to our application. It will automatically configure our application's logging and assets to work correctly with Heroku. Let's open our application's Gemfile and add the following line:

gem 'rails_12factor', group: :production

As we've added a new gem, we'll want to run bundle install to update our application's dependencies:

$ bundle install

We'll need to make another commit with our latest changes:

$ git commit -am 'Adding 12 factor gem'

This application uses a Postgres database. We'll need to add Postgres to our Heroku application. Let's do this now:

$ heroku addons:add heroku-postgresql:dev
----> Adding heroku-postgresql:dev to cryptic-chamber-6830... done, v3 (free)
      Attached as HEROKU_POSTGRESQL_GOLD_URL
      Database has been created and is available
      ! This database is empty. If upgrading, you can transfer
      ! data from another database with pgbackups:restore.

Ruby on Rails uses an environment variable to connect to the database. We can set this now using the promote command. This will assign our new database's credentials to the DATABASE_URL environment variable.

We'll use the database name given to us in the previous command as the argument in this command:

$ heroku pg:promote HEROKU_POSTGRESQL_GOLD
-----> Promoting HEROKU_POSTGRESQL_GOLD to DATABASE_URL... done

We're now ready to push our code to Heroku. We'll do this using Git's push command. We'll need to specify the heroku remote and our master Git branch:

$ git push heroku master
Initializing repository, done.
Counting objects: 92, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (79/79), done.
Writing objects: 100% (92/92), 35.83 KiB | 0 bytes/s, done.
Total 92 (delta 11), reused 0 (delta 0)

…

-----> Discovering process types
       Procfile declares types -> web
       Default types for Ruby  -> console, rake, worker

-----> Compressing... done, 37.1MB
-----> Launching... done, v9
       http://cryptic-chamber-6830.herokuapp.com/ deployed to Heroku

To git@heroku.com:cryptic-chamber-6830.git
   46345bc..583680c  master -> master

Now that our application's code is on Heroku, we need to completely set up our database by running migrations and seeding it with some data:

$ heroku run rake db:migrate
$ heroku run rake db:seed

Our app is now ready to use! We can quickly launch a browser and view it with the open command:

$ heroku open

Once our application is open, let's go to Refinery in the browser to register a user and start using the Refinery CMS.

First, we'll need to download the Ghost source code from GitHub. We'll clone an existing Ghost Git repository that's been set up to run on Heroku:

$ git clone https://github.com/mscoutermarsh/ghost_heroku.git
  Cloning into 'ghost_heroku'...
  remote: Counting objects: 16411, done.
  remote: Compressing objects: 100% (7480/7480), done.
  remote: Total 16411 (delta 8481), reused 16381 (delta 8455)
  Receiving objects: 100% (16411/16411), 8.55 MiB | 1.75 MiB/s, done.
  Resolving deltas: 100% (8481/8481), done.
  Checking connectivity... done

Let's navigate to the new ghost_heroku directory and create a new Heroku application:

$ cd ghost_heroku
$ heroku apps:create
  Creating fast-coast-3773... done, region is us
  http://fast-coast-3773.herokuapp.com/ |
  git@heroku.com:fast-coast-3773.git
  Git remote heroku added

The configuration for our application is in the config.js file. Let's open the file now and update the default production URL to reflect our new Heroku application's URL (given to us from Heroku in the previous step):

production: {
  url: 'http://my-ghost-blog.com',
  mail: {},

Commit the changes to Git:

$ git commit -am 'Updating production URL config'
  [master cd0ec0e] Updating production URL config
   1 file changed, 1 insertion(+), 1 deletion(-)

We'll use Postgres as our database for Ghost. We can create a new Postgres database now:

$ heroku addons:add heroku-postgresql:dev
  Adding heroku-postgresql:dev on fast-coast-3773... done, v3 (free)
  Attached as HEROKU_POSTGRESQL_SILVER_URL
  Database has been created and is available
   ! This database is empty. If upgrading, you can transfer
   ! data from another database with pgbackups:restore.
  Use `heroku addons:docs heroku-postgresql:dev` to view documentation.

We'll need to set up our new database as the primary one for our application by promoting it. In the previous command, Heroku gave us a unique database name. It follows the format of HEROKU_POSTGRESQL_COLOR_URL. We'll use that name as the argument for the next command:

$ heroku pg:promote HEROKU_POSTGRESQL_SILVER_URL
  Promoting HEROKU_POSTGRESQL_SILVER_URL to DATABASE_URL... done

Next, we'll need to set a configuration variable to let Node know which environment it's running on. Let's set it to production:

$ heroku config:set NODE_ENV=production

Our application now has everything it needs to be deployed. Let's push our repository to Heroku to deploy our code:

$ git push heroku master

Once the build process is complete, our blog will be up and running. We can now launch a browser from the command line to see the following screen:

$ heroku open

To access Ghost's admin panel, add /ghost at the end of the URL. We can then create an account and start playing with our new blog.

To view our currently running processes, we can use the ps command. It will show the type, the size, and exactly what's running:

$ heroku ps
=== web (1X): `bundle exec unicorn -p $PORT -c ./config/unicorn.rb`
web.1: up 2014/03/15 19:41:27 (~ 8s ago)

We currently have only one dyno running for this application. Let's scale it up to two; this will effectively double our application's capacity. Scaling processes are done with the ps:scale command:

$ heroku ps:scale web=2
Scaling dynos... done, now running web at 2:1X.

The scale command is very flexible. If we want, we can scale both dynos and workers at the same time:

$ heroku ps:scale web=2 worker=1
Scaling dynos... done, now running worker at 1:1X, web at 2:1X.

We can change the size of our dynos using ps:resize. Let's scale up our web dynos to 2X:

$ heroku ps:resize web=2x
Resizing and restarting the specified dynos... done
web dynos now 2X ($0.10/dyno-hour)

We can also scale and change the size in the same command. Let's dial our dynos back down to one and adjust the size to 1X:

$ heroku ps:scale web=1:1x
Scaling dynos... done, now running web at 1:1X.

To finish up, we can scale our workers back down to zero:

$ heroku ps:scale worker=0
Scaling dynos... done, now running worker at 0:1X.