Skip to content

Heroku

Jump to bottom Edit New page
csusbdt edited this page Oct 9, 2014 · 8 revisions

Requirements

For this assignment, you must:

  1. Create a folder called heroku in your course repository.
  2. Install node.js on your computer.
  3. Create a free Heroku account.
  4. Install the Heroku toolbelt on your computer.
  5. Setup Heroku on your computer.
  6. Create a Heroku app in your heroku folder.
  7. Test the app locally.
  8. Publish the app to Heroku.
  9. Test the app on Heroku.
  10. Create a README.md file in your heroku folder.
  11. In the README, describe what you learned and did, and give a link to your Heroku app.
  12. Publish the app to your course repository.

When you are finished with this assignment, your repository must have the following structure:

~/322/
|- git/
   |- README.md
|- heroku/
   |- README.md
   |- main.js
   |- public/
      |- index.html
|- node_modules/
   |- st/
|- Procfile
|- package.json

Detailed Instructions

Intro to Heroku

Heroku is a company that provides web application execution environments as a cloud service. The type of services it provides is referred to as "platform as a service" (PaaS). Heroku offers a free tier account, which we will use to publish a simple web application that serves static web pages.

In the subsequent course (CSE 405 Server Programming), you will learn more about writing programs that run in the Heroku execution environment and interact with a database server.

Creating Your Heroku Folder

Create a folder named heroku in your repository to hold some of the files for this assignment. Some files will go into the root folder of the repository. When you are finished with this assignment, the heroku folder should contain the following files and folders.

  • README.md
  • main.js
  • public/index.html

Also, you will have added the following files and folders to the root level of your repository.

  • Procfile
  • package.json
  • node_modules/

Working in Windows

It is important in this course, and in general when working as a programmer or system administrator, that you disable hiding of extensions for known file types. If you do not disable this feature, then you run the risk of naming files with incorrect extensions. You may also want to display hidden files and folders as well. These 2 settings are important for programmers to make when working in Windows.

Working in the Labs JB 358 and 359

If you are working on a lab machine, then you need to adjust your system path to run nodejs and heroku. To do this, add the following lines to ~/.bash_profile. If this file doesn't exist, then create it.

export PATH=$PATH:/opt/nodejs/bin
export PATH=/u/faculty/turner/public/bin:$PATH
export PATH=/u/faculty/turner/public/heroku-client/bin:$PATH

Installing Node.js

If you are working on a lab computer or on another system with Node.js already installed, then you can skip this section.

These instructions assume that you have cloned your course repository into a folder named 322 within your home directory. These instructions refer to the folder with the path ~/322, where ~ refers to the home folder. If you have cloned your repository into a different location, then adjust the instructions accordingly.

Install Node.js in your development environment. You can get this from the Node.js website.

If you have an older version of Node installed, you can simply install a newer version without uninstalling first.

Getting Heroku Setup

The Heroku Toolbelt is already installed on the lab computers, so if you are working on a lab computer, you can skip installation of the toolbelt. However, you still need to create a Heroku account.

Create a free Heroku account and install the Heroku Toolbelt. Note that you do not need to register a credit card for this purpose. You can find download links for the Heroku Toolbelt and other useful resources in the Heroku Dev Center.

If you install Heroku Toolbelt under Windows, I recommend that you install to c:\heroku (or other path that does not include spaces). This will allow the commands heroku and foreman to be run in the Git Bash shell.

Authenticate with Heroku with the following command.

heroku login

Use the username and password you used to setup a Heroku account. This command sends your ssh public key to Heroku, so you do not need to manually login when you use heroku commands in the future. Your ssh public key is stored in ~/.ssh/id_rsa.pub. If you regenerate public/private keys, you will need to run the heroku login command again in order to transmit your new public key to Heroku.

Also, there were bugs in the foreman command that make it difficult to get working under Windows. I posted a solution on Stackoverflow. The foreman command is optional for our purposes, so if you can't get it working, then skip it.

Creating Heroku App

Create folder ~/322/heroku and subfolder ~/322/heroku/public. The public folder will contain the static files that comprise your website.

Create a test HTML file ~/322/heroku/public/index.html with the word "hello" in it.

Create ~/322/heroku/main.js with the following contents.

var http = require('http');
var st   = require('st');

var port = process.env.PORT;
if (port === undefined) port = 5000;

var static = st({ path: __dirname + '/public', index: 'index.html' });

http.createServer(function(req, res) {
    static(req, res)
}).listen(port);

Use the Node Package Manager program to install the st library with the following command, which you should issue from the root level of the repository.

cd ~/322
npm install st

The npm command above will create a folder named "node_modules", under which it stores the st library and its dependencies.

Test the server with the following command.

cd ~/322
node heroku/main

In your browser, go to http://localhost:5000/.

When you deploy your application, Heroku will run the above command from a Procfile. For this purpose, create file ~/322/Procfile with the following contents. (Make sure the filename has no extension.)

web: node heroku/main

Decide on a name that you believe is unique across Heroku apps; subsequent instructions refer to this name as "a-unique-name".

Create file package.json with the following contents. Replace "a-unique-name" with your app name.

{
  "name": "a-unique-name",
  "version": "0.0.1",
  "description": "An app",
  "repository": {
    "type": "git",
    "url": "http://github.com/isaacs/npm.git"
  },
  "dependencies": {
    "st": "0.5.1"
  },
  "engines": {
     "node": "0.10.28",
     "npm": "1.4.9"
  }
}

You can optionally adjust the versions in package.json according to your system, although this is not necessary to get it working. Also, if you modify the versions, you need to make sure that Heroku supports the version you specify; in the past I have observed Heroku to not support most recent versions of node.

Heroku starts your app on its servers with the foreman command. It's possible to run the foreman command in your local development environment, but it takes time to configure Windows system to run it correctly. So we will omit this step.

Decide on a name for your site. Use this name to create a Heroku application. Omit the angle brackets in the following and replace "a-unique-name" with the name that you want to use.

heroku apps:create <a-unique-name> --remote heroku

The above command creates an alias named heroku in your local git repository that refers to the URL of the remote git repository that you use to deploy your app into Heroku. To see this, run the following.

git remote -v

Now, your local repository has aliases for 2 remote repositories: one for the course, named "origin", and another for deploying into Heroku, named "heroku". Web applications are deployed into Heroku as remote git repositories.

Deploying App to Heroku

Commit your changes to the local repository.

cd ~/322
git add .
git commit -m "heroku app created"

Deploy your app to Heroku by pushing changes to the remote repository that you create through the heroku create command.

cd ~/322
git push heroku master

Test in browser by going to https://a-unique-name.herokuapp.com/, replacing "a-unique-name" with your Heroku app name.

Working With a 2nd Computer

If you clone your remote repository to a second location, you will not get the definition of the heroku remote repository because remote references are only stored in local repositories. This means you need to re-define the heroku remote repository in your new local repository. Use the following command to do this.

git remote add heroku git@heroku.com:a-unique-name.git

Make sure you replace "a-unique-name" with the name you chose for your Heroku application.

Also, you'll need to login into Heroku from your new computer.

heroku login

You only need to log in once on a computer because the heroku login command sends your ssh public key to heroku, where it is cached and used to authenticate your computer for subsequent commands that connect to Heroku servers.

Documenting Your Learning

Create file ~/322/heroku/README.md. Add to it a description of the reading and experimentation you did to complete this assignment. Also add to README.md a link to your website running on Heroku.

Submitting Your Work

Push your changes to the remote course repository.

cd ~/322
git add .
git commit -m "completed heroku assignment"
git push origin master

Additional Reading

  1. Heroku Node.js Documentation: This is Heroku's documentation about using Node.js. It's good documentation, but is not specific to this class.
Add a custom footer
Clone this wiki locally