Deploying to Heroku: An introduction

Thanks to Matthew Wilkin for kindly helping to peer review this article.

In this article, you’ll learn about Heroku and how to deploy your web application to it.

If you’ve never heard of it, Heroku is a managed server platform for quickly deploying web applications. It automatically provisions server resources for you, and deployment is as easy as a git push to your app’s repository on Heroku. Best of all, you can deploy your app for free (provided it doesn’t get too much traffic), which makes getting started free and easy.

If you have a lot of traffic, Heroku can get a bit pricy; each node (or dyno, as they call them) will cost you $25 or more per month, and adding features like databases will increase that a bit. That said, it’s a heck of a lot cheaper than hiring a devops team to deliver the stability and ease-of-use that Heroku offers.

Before We Start

If you want to follow along from here, you’ll need to make sure you have a few things handy.

Go download and install the Heroku Toolbelt. This is the command-line utility that we’ll be using to configure the project.
Make sure your project is using Git. You should know what git is, but if you don’t, here’s some light reading. If you don’t have a project, just make sure git is installed.

If you already have something ready to go, skip the next section and go straight to Creating a Heroku Project.

Our Example Project

More from this author

To assemble this example project, you’re going to need pip (which is good to have handy for any Python development anyhow). We’ll be using a Python project written using Flask, a web microframework for Python, but you can mostly follow along with any project (it should be obvious which parts are language-specific and how to adjust them).

If you have something ready, skip ahead to the next section. If you need a project, set up a project folder as follows (you don’t have to call it myproject):

/myproject
  /templates
    index.html
  app.py
  requirements.txt

And fill them out like so:

app.py:

import os
import flask


app = Flask(__name__)

@app.route("/")
def index():
    return render_template("index.html")


if __name__ == "__main__":
    app.run(port=os.environ.get('PORT', '5000'))

templates/index.html:

<!doctype HTML>
<html>
  <head>
    <title>My example project</title>
  </head>
  <body>
    <h1>This is my project.</h1>
    <!-- feel free to get a bit more creative here -->
  <body>
</html>

requirements.txt

Flask==0.10.1

then run:

pip install -r requirements.txt

After that, make sure everything is working by running python app.py and navigating to http://localhost:5000/. If all went well, you should see index.html rendered there.

Creating a Heroku Project

Here comes the easiest thing in the world. Open a terminal, cd to your project directory, and run the following commands (skip the git one if you already have git in your project):

$ git init
$ heroku create
Creating app... done, stack is cedar-14
https://calm-lake-56303.herokuapp.com/ | https://git.heroku.com/calm-lake-56303.git

With this command, Heroku:

generated a name for us (we could have chosen one by running heroku create myproject instead)
assigned us a url and a git repository
initialized the heroku remote repository in git for us.

We’re just about ready to deploy, but it’s good to know what’s about to happen first. Let’s learn a bit more about how Heroku can know what to do with your code — and how to make sure it’s satisfied.

An Aside on Buildpacks (or, how Heroku Recognizes Your Project)

Heroku projects are managed by buildpacks, which are in essence instructions for fetching dependencies, building and running your project. There are officially supported buildpacks for Node.js, Ruby, Java, Clojure, Scala, PHP, Python, and Go. You won’t need to tell Heroku what you’re using for these; instead, Heroku will guess what the project is, based on some conventions and heuristics regarding dependency management. For example, a requirements.txt file in your project directory, as exists in the example project above, indicates a Python project. Here are the dependency files that Heroku will use to automatically detect your platform for other platforms:

Node.js: package.json
Ruby: Gemfile
PHP: composer.json
Java: pom.xml
Scala: build.properties
Clojure: project.clj
Go: Godeps/Godeps.json

If you’re using a different language, or using a different build tool for one of these languages, you can also use a third-party buildpack. Heroku maintains an extensive directory of these, so check there before giving up on your preferred language. You can set the buildpack using the git repository URL; for example, to use Upworthy’s Clojure Boot buildpack, you could run this command in your project directory:

$ heroku buildpacks:set https://github.com/upworthy/heroku-buildpack-boot

You might even find an unlisted buildpack on Github — just check around to make sure it’s safe to use!

Setting up Your Procfile

Everything we need is in place, except for one component. Heroku uses a file called Procfile to tell it what it should be running. For your getting started project, you’ll probably just want to specify a web process, but you can also specify worker jobs.

Since we run our app with python app.py, we will put the following in our Procfile:

web: python app.py

(Later, you might want to use something more performant; you can use Gunicorn by adding it to your requirements.txt and replacing your Procfile contents with web: gunicorn app:app -b 0.0.0.0:$PORT).

Deploying Your Project

Add Procfile to your repository:

$ git add Procfile && git commit -m "added Procfile"

Then, use git push to deploy to Heroku

git push heroku master

Congratulations

Your app should be deployed on Heroku. Navigate to the URL that Heroku tells you, and you should see your home page.

That’s it. That’s the whole article. That’s your life with Heroku now; just push your commits and they get deployed immediately. How crazy is that?!

Some Bonus Commands

Just in case you’re not satisfied, here’s some assorted things you might want to do with the heroku command:

heroku config:set MY_ENV_VARIABLE=some_value: Set a persistent config value. Useful for things like database passwords and other configuration.
heroku ps:scale web=5: Sudden traffic surge? Scale your process up to 5 web dynos in an instant. Note that this will cost you $125 at $25 per dyno, so use this with caution. To scale back down after you fall off Reddit, run heroku ps:scale web=1.
Made a mistake? You can list your app’s releases with heroku releases. To roll back to a certain release, run heroku rollback <release identifier>. Or just run heroku release to undo the latest release.

You can also manage most of these from Heroku’s dashboard, if you prefer.