Octomaton: Hello World on Heroku (with Python)

When I first heard about heroku it sounded amazing, but when I tried to use it I felt quite deflated, as I found it really hard to use. So once I got a Hello World working I thought I would write a tutorial to help anyone else out there. Please note, I use ubuntu, so some things will be a little different if you use another OS.

Wait, what is heroku?

Heroku is basically a web hosting platform, but it is one that is set up so that you can (in theory) easily deploy web apps using a variety of languages and, importantly, scale them should they become successful. However, for a cheapskate like myself, one of the main selling points is that before your web app gets successful, it is free!

Step 1: Creating an app

There are two ways of creating an app: from the command line; or through the heroku website. If you’re reading this article you probably want the easy way! There is a good tutorial on the heroku website regarding creating an app from the command line , and then renaming it; but it is probably much easier to do it through the website: go to your dashboard and click on “Create a new app”.

Step 2: Install heroku toolbelt and "Heroku Push"

Download and install the heroku toolbelt from toolbelt.heroku.com. This is a set of tools that make it much easier for your local computer to talk to the heroku website using the command line. It will make the next steps much easier. You can do this from the command line by using:

wget -qO- https://toolbelt.heroku.com/install-ubuntu.sh | sh

"Heroku Push" is a fricking brilliant tool which allows you to publish things to heroku without using git. Insulting git seems to generate a torrent of hatred from purists out there, but I am afraid I have found it nothing but confusing! Actually, given how much love for git there is out there, it must have something going for it, but I think it is much more useful for several people working on the same complex project; I am a solo developer trying to deploy fairly simple apps, and would much rather not use it. There, I said it.

Go to the git page for heroku-push for more information (OK, you have to use git to get this tool!), but you can just install it from the command line:

heroku plugins:install https://github.com/ddollar/heroku-push

Later on, I will recommend using the command "heroku push" from the command line - this will not work without installing this plugin.

Step 3: Assemble the app’s files

There are three files that you need in order to make this work. I would recommend keeping these files in a folder together somewhere, i.e. a folder within the directory you are using for this project:

requirements.txt
Procfile
hello.py

requirements.txt

The requirements.txt file tells heroku which plugins it needs to load in order for your app to work. I have played around a bit with including some things and leaving some out, such that I think that what I've put here to include is the minimum needed in order for your python code to work, The flask framework depends on the Jinja2 and Werkzeug libraries, and the gunicorn plays the part of the server. Save the following four lines in your requirements.txt file:

Flask==0.9
Jinja2==2.6
Werkzeug==0.8.3
gunicorn==0.17.2

Procfile

Save a file (without an extension) named “Procfile”, with the following contents:

web: gunicorn hello:app

While I must admit I have nigh-on zero experience of using gunicorn, I believe that it is a rudimentary web server called by heroku, which is in turn told what files to serve. So the “hello:app” part tells gunicorn to load the right python file. You can put anything you like here, but it must have the same name as the python file. In other words, you could put "web: gunicorn foobar:app", but you would have to save your python file as "foobar.py".

Python file (hello.py)

Note that this can be called anything, but must be a python file. In other words, it must have the python file extension (“.py”), but could be mygreatapp.py, or even myrubbishapp.py, or whatever.py. However (see above), your Procfile would have to change to reflect this.

from flask import Flask

app = Flask(__name__)

@app.route('/')
def source():
 html = 'Hello World!'
 return html

Obviously we have defined a function, “source()” within this python file (this function can be called whatever you want). From what I can tell, the first function defined in the file is called automatically, but none below that. I’m not 100% sure, but I believe that any normal python will work within this function (I’ve not really played around with heroku much yet, so there may be limitations). It seems like anything returned by the function (i.e. the final line) is printed out to the webpage, effectively being the html source file.

Step 4: Deploy your app to heroku

Open the terminal (as I mentioned, I’m using ubuntu - I’m not sure how you do this with any other OS, but what we are trying to achieve is to upload the working directory to heroku). First, log in to heroku using the following command (entering your email and password at the prompt):

heroku login

Change to the directory where the files (defined above) are held.

cd path/to/project/directory

Deploy your app to heroku using the following command, making sure to change the relevant part to the name of your app:

heroku push --app name-of-app

For example, my app here is called "octomaton-hello-world" (see the picture in Step 1 above), so I would enter "heroku push --app octomaton-hello-world". Go and make yourself a cup of tea: it could take a good couple of minutes for the app to deploy.

Finally, go to your app's url to test it; for this app it is octomaton-hello-world.herokuapp.com. Hopefully it should be saying hello!

Hello World on Heroku (with Python)