Heroku crash course
===================

`Heroku`_ is a web service that provides (limited) free hosting for
web applications in many programming languages, including Python. This
document is a crash course in setting up a Python application on
Heroku. We set up the `example application
<orie-6125-webapps-example.git>`_ from before.


Registration
------------

Head over to `Heroku`_ and make an account.


Downloading the toolbelt
------------------------

We need to install some programs to let us interact with Heroku. They
want you to run

.. code-block:: bash

   wget -O- https://toolbelt.heroku.com/SOMETHING | sh

where ``SOMETHING`` is really ``install-ubuntu.sh`` but blindly piping
output like that to ``sh`` is a horrible idea so I'm making it hard to
copy and paste it. Instead we are going to running

.. code-block:: bash

   wget -O- https://toolbelt.heroku.com/SOMETHING > tmp.sh

And then inspect ``tmp.sh``. We find

.. code-block:: bash

   #!/bin/sh
   {
       echo "This script requires superuser access to install apt packages."
       echo "You will be prompted for your password by sudo."
   
       # clear any previous sudo permission
       sudo -k
   
       # run inside sudo
       sudo sh <<SCRIPT
   
     # add heroku repository to apt
     echo "deb http://toolbelt.heroku.com/ubuntu ./" > /etc/apt/sources.list.d/heroku.list
   
     # install heroku's release key for package verification
     wget -O- https://toolbelt.heroku.com/apt/release.key | apt-key add -
   
     # update your sources
     apt-get update
   
     # install the toolbelt
     apt-get install -y heroku-toolbelt
   
     # install ruby if needed (vervet)
     if ! type ruby >/dev/null 2>&1; then
       apt-get install -y ruby
     fi
   
   SCRIPT
   }

Assuming we trust Heroku, this script looks fine to run. Go ahead and

.. code-block:: bash

   chmod u+x ./tmp.sh
   sudo ./tmp.sh

to install the toolbelt.


Log in
------

We need to log in each session. Run

.. code-block:: bash

   heroku login

and provide the requested information.


Initialize the application locally
----------------------------------

Move to the application directory, and run

.. code-block:: bash

   heroku create

This adds a new remote ``heroku``, which we can see with ``git remote
-v``.


Deploy
------

Run ``git push heroku master`` to push your master branch to the
``heroku`` remote. This will re-build your Heroku application. You
might need to run

.. code-block:: bash

   heroku ps:scale web=1

to set up the instance.


Visit the application
---------------------

Run ``heroku open`` to point your web browser at the application.

.. _Heroku: www.heroku.com