.. _use_heroku:

#############################
 Using Heroku
#############################

Heroku provides a free web application deployment services, integrated with 
the Cloud9 development environment through Git and GitHub. Following is a 
brief outline for configuring and deploying a project on Heroku.

Install Heroku Tools
=============================
+  Open a project in Cloud9
+  In the Cloud9 Project, choose :menuselection:`View --> Console` from the menu
+  At the console command line, type::
  
      c9pm install heroku

+  To make sure that your install was successful, and to get ready to use heroku,
   run the following command in your Terminal::
    
      heroku login
  
   Enter your heroku username and password when prompted.

Add Heroku Server to Project
=============================

+  Open a project in Cloud9
+  In the Cloud9 Project, choose :menuselection:`View --> Console` from the menu
+  At the console command line, type::
  
      heroku create
  
   This will create a heroku server for your app, and configure your git 
   repository with a remote location where you can deploy your app.

+  To see the new git heroku deployment branch, type::

      git remote -v
 
+  Open in a new browser tab, and bookmark, the url of your new heroku server,
   which you will see in the output of the ``heroku create`` command. The URL 
   will look similar to this:: 

      random-word-1234.herokuapp.com

+  After making changes to the project in Cloud9 and pushing to the GitHub 
   repository, deploy changes on Heroku with the additional command::

      bash doc-deploy.sh

+  Now you can view your live site at your heroku server URL (which you 
   bookmarked earlier).

.. note:: Did you notice? the :file:`doc-deploy.sh` deployment command file was 
   the same for either **gh-pages** on GitHub or **heroku**. Curious students 
   should open this program in the editor and investigate this piece of magic.

Heroku Static Deployment
=============================

Ordinarily Heroku rejects static HTML sites and refuses the deployment, because
Heroku is designed to host dynamic web applications instead. Heroku is tricked 
into hosting the Sphinxdoc HTML as if it were a :program:`PhP` site by the 
presence of two files, generated by the :file:`doc-newproject.sh` script::

   touch _static/index.php
   echo 'php_flag engine off' > _static/.htaccess

This deployment idea is courtesy Kenneth Reitz [#]_. Other techniques for making 
static deployments using special packs for :program:`Ruby` or :program:`PHP` are 
mentioned in the references. [#]_ [#]_ [#]_

----------

#############################
Basic Access Authentication
#############################

GitHub's **gh-pages** provides free deployment for static sites comprised of 
HTML pages. HTML itself does not provide security mechanisms for private sites, 
however; this is a web server function which requires dynamic site deployment.

User authentication and site security in a web application generally depends on 
computer language libraries, server configuration files, and a host of other 
stuff specific to the project. However, practically every web server supports 
basic access authentication through configuration file :file:`.htaccess`. [#]_
Used properly, this will provide what is referred to as "Pretty Good Privacy" 
(PGP).

By combining Bitbucket private repository hosting with dynamic deployment on 
Heroku, we can develop and test static and dynamic projects in the cloud with 
privacy. Here is how:

.htaccess script generator
==============================

+  Open project file :file:`_static/.htaccess` in your editor. It should contain 
   one line, :kbd:`php_flag engine off`, as described previously.
+  Open site 
   `htaccess authentication <http://www.htaccesstools.com/htaccess-authentication/>`_
   in a separate browser tab. [#]_
+  Type an authentication message in :guilabel:`Auth Name`.
+  Type :file:`/app/www/.htpasswd` in :guilabel:`.htpasswd File Location`.
   
   .. image:: _images/09_htaccess-1.png

+  Click the button, :guilabel:`Create .htaccess file`. 
+  Select the text on the resulting page, copy it, and paste it into file 
   :file:`.htaccess` below the existing command.
+  The resulting text in .htaccess should look like::

      php_flag engine off     
      AuthType Basic
      AuthName "Access restricted - login"
      AuthUserFile /app/www/.htpasswd
      Require valid-user

+  Save the :file:`_static/.htaccess` file.

   .. note:: If you are having trouble finding the :file:`.htaccess` file, you 
      may have forgotten that files starting with a dot (.) are hidden. Remember 
      to show hidden files.
   
.htpassword auth generator
==============================

+  Create a new text file in folder :file:`_static`, name it :file:`.htpasswd`,
   and open it in the editor.
+  Use `htaccess passwords <http://www.htaccesstools.com/htpasswd-generator/>`_
   generator to create *Username:Password* strings. 
   
   .. image:: _images/09_htaccess-2.png
   
+  Copy each created string and paste it into :file:`.htpasswd`, one string per
   line.
+  Save the file :file:`_static/.htaccess` into your project.

Deploy to Heroku
==============================

Deploy your project to Heroku with the :file:`doc-deploy.sh` command. Then 
display the running app in the web browser. You should be asked for 
authentication credentials.

------

.. rubric:: Footnotes

.. [#] `Kenneth Reitz <https://github.com/kennethreitz>`_, Static sites on 
   heroku cedar, http://kennethreitz.org/exposures/static-sites-on-heroku-cedar.

.. [#] `Guillermo Garron <http://www.garron.me/about.html>`_, Hosting jekyll 
   site for free on heroku, 
   http://www.garron.me/blog/deploy-host-jekyll-static-site-free-heroku.html.

.. [#] `Static build pack <https://github.com/aaltsys/heroku-buildpack-static>`_
   
.. [#] `Static article <http://yobriefca.se/blog/2012/08/21/securely-serving-static-files-on-heroku/>`_

.. [#] Linked from Wikipedia, 
   `Basic access authentication <http://en.wikipedia.org/wiki/Basic_access_authentication>`_.
   
.. [#] `Andreas Gehrke <http://www.agehrke.com/about/>`_, web service linked at 
   `.htaccess Tools <http://www.htaccesstools.com/>`_.