Edit Go To Admin Logout

Ruby Off Rails, Part 1: Creating your very first Ruby web application using Sinatra and Heroku

So, how about writing a small Ruby web application and deploying it to Heroku? It's really quite easy – Ruby is more than just Rails, and for simple applications there are simple alternatives. Like Sinatra. Sinatra is awesome.

Don't let this fool you, though; you can build more than just simple stuff with Sinatra. It's just a whole lot closer to the metal than Rails. Don't worry, we'll start off simple – for the time being, you'll be building a simple “Hello World” style app. That may not sound very exciting, but getting everything set up and pushed to the web is pretty much the most complex and at the same time important part, so I'd like to dedicate this first chapter to that. Once I get around to writing more chapters, we'll be adding stuff to your app that, if you're new to the world of Ruby, will blow your mind. Promised!

Before we get started, please take note that we'll also try to get the application running on your local system before deploying it to Heroku. In some cases this can be the most complex part of getting started with Ruby. You'll also be using the command line a lot. If you're new to all this, don't let it scare you; it's really not as hard as it may look, and we were all new to this stuff at some point. I'm sure you'll be fine.

Preparing your system

In order to get started, you're going to need Ruby (awesome programming language) and Git (awesome version control tool). If you're completely new to this stuff, the Heroku Toolbelt will get you started with everything you need. It's a cool little package that comes with recent versions of both Ruby and Git, so even if you're not going to use Heroku, it's a nice and fast way of getting your system ready for development.

If you've dabbled in Ruby before, you'll probably know what you're doing – otherwise, please consult Google for up-to-date setup instructions. (Also, don't forget to install the heroku gem!)

Once you've managed to get your system set up for development action, you should have access to the ruby and gem command line tools. gem is part of RubyGems, Ruby's official package management system. Use it to install a gem called Bundler, like this:

gem install bundler

That's it. Now let's go code something!

Building your application

Now for the fun part! Go ahead and create a new, empty directory, using a catchy name of your choosing. This directory will hold your Ruby web application. We'll be adding a couple of files. I'm going to explain what each one does. Let's do this.

Gemfile and Gemfile.lock

First of all, create a file called Gemfile (capitalization matters! Capital G, dawgs). Remember the Bundler gem you installed earlier? Your application will be using a bunch of additional gems, and Bundler takes care of these dependencies. In hopefully more simple terms, Bundler makes sure that your system (and, later, your server) has all the stuff installed your application needs.

Add the following to your Gemfile:

source :rubygems
gem 'sinatra'
gem 'thin'

The first line tells Bundler to fetch its gems from RubyGems. The other two lines tell it that our application will be using the sinatra and thin gems. (Thin is a great Ruby web server. Don't worry about it for now.)

Now let Bundler do its magic by running the following command from within your applications directory:


The bundle command parses your Gemfile, installs required dependencies, and creates (or updates) a file called Gemfile.lock (which will now have appeared in your application's directory). You're never going to edit Gemfile.lock yourself, but it serves a very important purpose, as it tells Bundler exactly which versions of your app's dependencies (and their dependencies, and so on) are installed. It basically makes sure that you're going to be using exactly the same gem versions on your server as you are on your local system. In the crazy fast-moving world of Ruby, this is a very good thing.

Another hopefully simple way of describing the difference between Gemfile and Gemfile.lock is this: in Gemfile, your application tells Bundler which gems it wants; in Gemfile.lock, Bundler tells your application which gems it's getting.


Now create a new file called config.ru. This somewhat awkwardly named file is an important part of the Rack specification (a common interface for Ruby web applications) and forms the main entry point into your application. For now, just think of it as your main code file.

Add the following lines to config.ru:

require 'rubygems'
require 'bundler/setup'

These will make sure that whenever you run your application, Bundler will not only prepare your application's dependencies to be used, but already load them. Fancy!

Now add the following lines to the end of your config.ru:

get '/' do
  "Hello, Ruby, Sinatra and Heroku world!"

run Sinatra::Application

Now, granted, what you're looking at is really just a simple “Hello World”-style app. Not very exciting, but we need to get started somewhere, right? Let's go through the lines. It's almost self-explanatory; the code block starting with get tells Sinatra to map the enclosed code (which is just a string) to GET requests on the root URL ('/') of your application. This is pretty much everything Sinatra does; it maps code to incoming requests. Whatever that code returns will be sent back to the user's browser. Right now we're just returning a simple, static string, but Sinatra leaves the construction of the response completely up to you. You're free to absolutely go crazy, and don't worry, go crazy we will! Uh, in a later chapter.

The run line finally hands over control to Sinatra. There's a whole lot more stuff you can do with Rack, but we'll go there later. Hey, did you know that Rails applications are really just Rack apps, too?

Running your application locally

Guess what, you're done already. You've written your first fully-working Ruby web application. Granted, it's not excessively exciting; the good news is that from this point onwards, adding stuff – exciting stuff! – is going to be really easy. Trust me, I'm a professional.

You can now run your application locally to see if it's working:

bundle exec rackup -p 3000

This will start your application on port 3000, so you should be able to access it through http://localhost:3000. If you're getting some kind of error message, then I'm a lousy teacher.

Deploying your application to Heroku

Deploying a Ruby application to a web server can be very complicated thanks to the multitude of options available (like different Ruby runtimes). For this tutorial, we'll be deploying your application not to your own web servers, but to Heroku, a fantastic cloud hosting service that gives you enough resources for small apps for free and is optimized for Ruby applications (Matz, the inventor of Ruby, works for them).

Before you continue, please create a Heroku account if you haven't done so already. It's free, and you will be able to push your application there without even having to provide payment details.

Once you've created an account, please run the following command:

heroku login

This will bind your local Heroku tools to your newly created account and also generate and register an encryption key if you don't have one already.

Creating a Git repository

We will be using Git (a fantastic and extremely popular version control tool) to push your application's code to Heroku. First of all, we need to put your application's directory under Git's control. Within that directory, run the following commands:

git init
git add .
git commit -m "Initial commit"

git init configures the directory to be a Git repository (unlike other version control tools, Git repositories and working copies are pretty much the same thing), git add . tells Git that you want to track all of your application's files (Gemfile, Gemfile.lock and config.ru, remember?), and git commit finally creates an initial commit containing your files. (If you're interested in reading up on how Git works, I recommend the Git Community Book.)

Configuring Heroku

Now we're going to ask Heroku to create a new, blank application on its servers. Within your application's directory, issue the following command:

heroku create -s cedar

This, among other things, should print the URL your application will be using. It will probably be somewhat strange looking, as Heroku will have decided on a random name for your application. Don't worry, you can change that name later; you can even assign your own domain names to your Heroku applications, but more on all that in a later chapter (or just peruse the relevant documentation).

Now all that's left to do is to push your application's code – or rather: Git commits – to Heroku. Issue the following command:

git push heroku master

This will not only push your code to Heroku, but also deploy and start your application.

Believe it or not, but you're done – your Ruby application is now live! You can open it like this:

heroku open

This will open your application in your browser, live and ready to be, err, used. Okay, it's still only a glorified “Hello World” example, but as I said earlier, you'll be surprised by how easy it is to add the really cool bits. Yay!

End of Part 1

That's all for now! You've learned how to get your system ready for Ruby development, created your very first (albeit very simple) Ruby web application using Sinatra, and successfully deployed it to Heroku. Ah, exciting times. In part 2 we will be adding interactivity, view templates and layouts. In later chapters, I'd like to touch on advanced topics like HAML, SASS (oh, sweet SASS), caching and going all-out crazy with jQuery and CoffeeScript, so stay tuned!