Heroku is a new approach to deploying web applications. Forget about servers; the fundamental unit is the app. Develop locally on your machine just like you always do. When you’re ready to deploy, use the Heroku client gem to create your application in our cloud, then deploy with a single git push. Git allows you to have multiple source repositories all at the same time. By making Heroku just another source repository, you can push your code and deploy your application in one easy step.

Prerequisites

Before using Heroku there are three simple requirements:

1. Run your Ruby application locally: See Getting Started with Rails. We recommend using Ruby 1.9.2 for application development. Using the Ruby Version Manager, you need only type rvm install 1.9.2 && rvm use 1.9.2 --default

2. Install Git: On a Mac, Windows, or UNIX/Linux

3. Create a Heroku account and install the Heroku gem

Getting Your App on Heroku

Now that you have your application running locally, let’s deploy it to Heroku:

1. Track your application with Git

If you’re already using Git with your application, skip to the next step. If you’re not yet using Git to track your application, run this:

$ cd PATH/TO/MY_APP
$ git init
Initialized empty Git repository in .git/
$ git add .
$ git commit -m "new app"
Created initial commit 5df2d09: new app
44 files changed, 8393 insertions(+), 0 deletions(-)

2. Set up your SSH keys

Git uses SSH as its secure transport protocol. You will need to generate a public SSH key and upload it to Heroku. Follow the instructions at Github for Mac, Windows, or Linux for generating keys.

3. Create your Heroku application

At the command line, run heroku create. The first time you do this, you’ll be asked to enter your Heroku credentials. Once you do, your email address and an API token will be saved to ~/.heroku/credentials, so you won’t have to provide them again.

This first use will also upload your public SSH key so you’ll be able to push and pull code.

$ heroku create
Enter your Heroku credentials.
Email: joe@example.com
Password: 
Uploading ssh public key /Users/joe/.ssh/id_rsa.pub
Created http://high-sunrise-58.heroku.com/ | git@heroku.com:high-sunrise-58.git
Git remote heroku added

The last line shows the name of your new Heroku app; in this case, it’s “high-sunrise-58”, and is available at http://high-sunrise-58.heroku.com. If you were to visit that URL before pushing your application code (either by typing it in or running heroku open), you’d see a standard Heroku welcome page.

On the next to last line, there’s another important piece of information: git@heroku.com:high-sunrise-58.git. This is the Git repository address for your new Heroku app, and if you check the output of git remote show heroku you can see that the heroku gem added it as a remote for you automatically.

4. Push your application to Heroku

$ git push heroku master
Counting objects: 65, done.
Compressing objects: 100% (58/58), done.
Writing objects: 100% (65/65), 80.54 KiB, done.
Total 65 (delta 14), reused 0 (delta 0)

-----> Heroku receiving push
-----> Rails app detected
       Compiled slug size is 0.1MB
-----> Launching....... done
       App deployed to Heroku

To git@heroku.com:high-sunrise-58.git
 * [new branch]      master -> master

5. Bootstrap your database

Your app is now running on Heroku with an empty database. Depending on your framework, run the appropriate command to set up your DB. For Ruby on Rails, run:

$ heroku rake db:migrate
(in /mnt/home/slugs/41913_b81cc1e5813c58c443e4120aff984d006f36ef20/mnt)
== 20081118092504 CreateWidgets: migrating ====================================
-- create_table(:widgets)
   -> 0.0519s
== 20081118092504 CreateWidgets: migrated (0.0520s) ===========================

That’s it, your app is now running on Heroku! You can take a look at it in your default web browser by running heroku open.

Next Steps

Now that your application is running, it’s easy to push updates:

1. Develop and test changes locally.
2. Commit code to git.
3. Push your changes to Heroku with git push heroku.

Additional Resources

• Heroku Platform Constraints
• Renaming Apps From the CLI
• Deploying with Git