In 2009 I wrote a tutorial called EC2 for Poets, and updated it in 2012. I wanted to see if it was possible to teach regular computer users to set up and run a server. I felt that setting up a server could be no more complex than installing and learning how to use PhotoShop (something I have never mastered) or a spreadsheet.

Lately I've become interested in Node.js. I've learned how to write Node apps, and have a couple of simple ones running, and doing things for me and some courageous users.

And the question comes up -- how easy is it to set up a Node server?

The answer -- pretty easy, once you know how to.

So that's what I'd like to do now. Tell you how to do it.

With the caveat that I've just learned myself, with the expert and patient guidance of a long-time friend -- Eric Kidd. He's really the author of these instructions, I've just tested them and written them down.

You're using a Mac, I hope

I'm writing these instructions assuming you're using a Mac. It'll work similarly if you're using Linux, and I'm told there are some small differences if you're on Windows. I haven't tried it there.

Before starting

Create an account on heroku.com. In this regard it works like every other site, so I won't insult your intelligence by giving you detailed instructions for this part of the experiment.

Launch Terminal

In the Applications folder, there's a program called Terminal. Launch it. This is how you communicate with Heroku from your computer.

Install the Heroku toolbelt. Follow the instructions on the Heroku site.

Get my example app

I have a simple Node app called fargoPublisher. Download the project using this link. Unzip it. Change the name of the folder to fargoPublisher.

It doesn't matter where you put the folder, but we're going to have to refer to it later, so let's assume you put it on a disk named myworld.

Name your app

You need to come up with a unique name for your app, one that isn't used elsewhere in Heroku. It could be a little tricky, but you'll get an error message if you choose one that someone else is using. In the instructions below, I use the name purplenutter.

Magic incantations

Type these commands in the Terminal app, exactly as they appear here.

cd /myworld/fargopublisher

git init

git add package.json publisher.js

git commit -m "Initial source code"

heroku create purplenutter

git push heroku master

Did it work?

If it worked you should get a confirmation message from Heroku.

And your app, if it was named purplenutter, will be at http://purplenutter.herokuapp.com/.

Setting environment variables

There's one more step to getting the app running for real, if you want to, you have to set a couple of environment variables so that it can write to your S3 bucket instead of mine (assuming you have an Amazon account).

There are four variables you have to set: the AWS access key ID, and secret access key, the path to a folder in one of your buckets, and a domain name. To test out whether the app is running you don't have to supply real values, just something -- so the program can access them.

You set an environment variable like this:

heroku config:set AWS_ACCESS_KEY_ID=OHBEAUTIFUL --app purplenutter 

heroku config:set AWS_SECRET_ACCESS_KEY=FORSPACIOUSSKIES --app purplenutter 

heroku config:set fpHostingPath=/mybucket/users/ --app purplenutter 

heroku config:set fpDataPath=/mybucket/data/ --app purplenutter 

heroku config:set fpDomain=helloworld.com --app purplenutter 

Enter each of these commands into the Terminal app.

Each time you do it, your app will restart.

The proof it's running

Enter this into your browser, substituting the name of your app:

http://purplenutter.herokuapp.com/version

You should get back a number, something like 0.59. If so -- it's running!

You should also visit your app on the Heroku site. To do so, go to the Apps page, and click on the link to your app. You're such a geek! A successful one!

What if you make a change?

No app is ever finished, you'll want to add features, fix bugs.

When you've made a change, here's the prayer you need to tell Heroku-san.

git commit -a -m "Update"

git push heroku master

It's free

It's really cool that Heroku will run this server for you for free, for as long as you want. If your service becomes popular then you have to pay them to run it. But as long as it's just for you and some friends it's free.

Amazon S3 and Heroku

I've been building my apps to work with Amazon S3 for storage. It think it's a really good combination. My apps store their state in S3 objects, which are fast and really cheap to store and serve. And I'm pretty sure Heroku runs in Amazon's cloud, so access is very fast.

Git and Heroku

Eric sent me an email after I got my app running, explaining how Git and Heroku work together. These are literally Eric's words, I just pasted them in here and formatted them.

Git stores your source code in a repository. This contains all your files, their history, your commit messages, etc.

Repositories come in two flavors:

• Local repositories. These look like ordinary directories of source code, but they contain a hidden ".git" directory with all your history and metadata. For example, when we run "git init" in fargoCounters, it creates a directory "fargoCounters/.git" and fills it with various things.

• Remote repositories. These are basically a bare version of your ".git" directory, without a surrounding directory full of source code. By convention, these are named something like "fargoCounters.git", and they typically live on a server somewhere. You can have any number of remote repositories: maybe none, maybe one on GitHub, maybe a bunch.

When you "commit" changes, they go into your local repository.

When you "push" changes, it takes the changes that were committed to your local repository and copies them to a remote repository. When you "pull" changes, you copy from a remote repository into your local repository. Using push and pull, you could move code around between several remote repositories, which is very useful for a team. For example, I could create my own fargoPublisher repository will a bunch of changes, and you could "pull" from my remote repository to your local repository, and then (if you like the changes), you could "push" them to your repositories on GitHub and Heroku.

Heroku basically acts like a magic remote repository for your app. You commit changes to your local repository, and push them to Heroku using 'git push heroku master'. But unlike a regular remote repository, when Heroku receives your changes, it automatically recompiles your app, deploys it to a server, and restarts your app using the new code.

Git is frankly a pain in the ass, but once you finally get used to it, it's pretty nice, because it makes it easy to share changes. And GitHub is excellent. In a perfect world, git would be easier to understand, but our world is definitely imperfect. And on the bright side, at least git is standard in the Node.js and Ruby communities, so you only need to figure it out once and then you can use it for all kinds of stuff. It's better to have once slightly ugly solution that everybody uses than to have 37 different solutions that lock in the users.

Questions?

That's what the comments section is for, below.

Happy Heroku-ing my new geek friend!

PS: One of the reasons I wanted to list all the steps was so we could shorten the list. I explained the process in this post.