Developer. Gamer. Yo-Yo Thrower.

Roll Your Own URL Shortener

Over the past few years we’ve seen the rise of URL shorteners. Sites that take big ugly urls and condense them down into short versions, there are literally hundreds, if not thousands of them out there (,, … etc). Years ago I made my own ‘’ solely because I wanted to learn a framework in PHP, and a URL shortening app is a fantastic functional example. About a year after it was up I re-wrote it in Python/Django. About 2 weeks ago I finished re-writing it again for Node.js. This little web app has come to represent my “Hello World” for learning a new language and web framework. This re-write was different though, it’s the first real project I’ve ever released on my own.

The project is called shorten-node and you can check it out on my github.

What you’ll need:

  • A short TLD
  • Heroku toolbelt
  • Basic web programming knowledge (or at least no fear of a command line)

What you’ll get:

  • A fully functional URL shortener with an API
  • Such great trendy web dev cred: “Just pushed my Node.js URL shortener to the heroku cloud … check out the diff on my github.”
  • So much attention from the opposite sex on twitter (“Is that a custom url shortener?! *swooon*”)

The first thing you’ll need is a short domain. It can be literally anything you can get your hands on. Getting weirder or less common TLDs can be a little expensive (.cm is about $100/year) and you may face restrictions that you’ll be unable to meet (often countries will require you to have a representative living in their country before letting you get a TLD from them). For the purposes of this post, I’m going to use my ‘’.

Open a terminal, and check out check out the code for shorten-node into a new folder. The folder name I’m using is ‘kish_cm’ – again feel free to sub in your own name here and anywhere else that you see “kish_cm”, “”, or the app name “kishcm-node” used.

git clone kish_cm
cd kish_cm

Heroku is a very cool new web app hosting platform. Since the app is tiny, we can use the Heroku cloud for free to start. You will have to put in a valid credit card to allow add-ons to be added in, but you can pick only the free add-ons and not get charged. We’ll be using the ClearDB MySQL Database addon, it gives you 5MB for free – I have about 1000 short urls and 10000 log entries that consumes 2MB. So depending on how much you use you can either upgrade to the $9 a month, or turn off stats gathering and make that 5MB go a very long way (such is the beauty of using the cloud). After you’ve signuped at Heroku, configured your SSH keys with them, and installed the toolbelt you can login in your terminal:

heroku login

We’re going to tell Heroku to provision us a new web app. We’re using a custom “buildpack” here, this allows us to use Node.js 0.6.x based web apps (by default Heroku only supports 0.4.x). I’ve named my app ‘kishcm-node’ here, I suggest you name yours whatever your TLD is without the dot.

heroku create --stack cedar kishcm-node --buildpack

We need a database, I decided to try one of the Heroku addons, but really any MySQL database that accepts a remote connection will do. To get the MySQL addon we need to login to the Heroku website. Once logged in you should see the app you just provisioned in your apps list. The ClearDB MySQL addon requires you to “verify” your account by adding your credit card information, we’ll use the free add-on so you won’t be charged. Once verified, click “add” on the ClearDB MySQL addon page and it will attach to your app.

Go back the the terminal. We’ll set an environment variable so shorten-node knows that it’s in a live/production environment.

heroku config:add NODE_ENV=live --app kishcm-node

We’ll check to make sure the ClearDB MySQL server was added to the app and that our NODE_ENV was set properly.

heroku config --app kishcm-node

We need to get the MySQL username, password and host from the config. You should see something that looks like this:

BUILDPACK_URL          =>
NODE_ENV               => live
PATH                   => bin:node_modules/.bin:/usr/local/bin:/usr/bin:/bin

Using your favourite text editor open settings.js from where you checked out the shorten-node code and update the live_domain and live_mysql objects. Update the live_mysql object to match the mysql URL, username, password and port that was outputted from the app config:

live_mysql: {user: 'xxxxxxxxxxxxxx', password: 'yyyyyyyy', dbname: 'heroku_zzzzzzzzzzzzzzz', host: '', port: '3306'},

The dev_domain and dev_mysql objects can be updated if you wish to do any development on a local machine – this is useful for making and testing changes in your app before pushing them live. It goes a little beyond the scope of this document, however the README file in the shorten-node github will walk you through setting up a local dev environment if you’re interested.

Next we need to initialize the database – this simply generates the database structure for our app to use. Do this by running the setup command. If it fails it will tell you the SQL error it encountered, otherwise it will print “DB Initalized for live”

node setup_db.js live

Now that our database is setup, and we’ve added our domain to the settings.js file our app is almost ready to deploy! We need to commit our changes to our local git repository and push that repository to Heroku. This sounds daunting but it’s really not that bad. Simply issue this git command:

git commit -a -m "Updated settings and initialized database."

Next we’ll need to configure your domain. This varies from one domain registrar to the next, so unfortunately I can’t walk you though this one, but what you’ll need to do is set DNS “A Records” for your domain. The Heroku documentation page has a little video walking you through how to do this with GoDaddy, but as I said, it will be slightly different from domain-provider to domain-provider. Once you’ve set your A record, you need to tell Heroku to listen for requests to your domain, do this by first enabling custom domains and then adding your domain.

heroku addons:add custom_domains
# Replace with the domain of your shortener
heroku domains:add

Once you’ve got that setup, you’re ready to deploy to Heroku. What’s really cool about this process is that it’s done entirely though Git – you don’t need to FTP any files around, or muck about with weird web GUIs. You simply push to their remote repo.

git push heroku master

If you get an error along the lines of “fata: ‘heroku’ does not appear to be a git repository” – we just need to make sure the Heroku remote repo is setup with our local git repo. Do this by simply issuing a git remote -v

git remote -v

You should see “ (push)” in that output (again, just a reminder, you should be using your own custom app name in place of ‘kishcm-node’ in these examples). If you don’t, you just need to add the remote repo like this:

git remote add heroku
#Now reissue the push command
git push heroku master

If you’re still having problems, check out the Heroku help documentation for git. However, if everything has worked you should see git output a bunch of messages from Heroku, ending with one that tells you that your app is deployed. Simple as that, your custom URL shortener is ready to use!

If you want to make changes, updating your app is super easy. Assuming you don’t already have code checked out (you’re starting from scratch on a different machine for example). You can easily get a copy of the current running app (replace ‘kishcm_node’ with your app name) by cloning the repo right off of Heroku like this:

git clone -o heroku

Now you can make whatever edits to the app you want to (again, replace ‘kishcm_node’ with your app name), commit changes locally, then push your local git repo to Heroku’s git repo for your app – all this is accomplished with a few commands like this:

cd kishcm-node
#edit some stuff
# Commit your changes and with a brief message saying what you've done
git commit -a -m "Updated widgets to be more widgety"
# Push changes to live server
git push heroku master

Again, when you push your changes you’ll see Heroku rebuild your app and also redeploy it live. Simple as that. You’re now a web engineer capable of deploying web apps to the cloud. Congratulations.

Back to

Table of Contents