(Nambu Network)

Self-Hosted Scripts for an URL Shortener:

Part 2 of this series of short articles on setting up your own URL shortener gives a discussion of an open-source software, that was used to run the very popular website until 2009.


Before Gravity4 acquired the domain, a nice URL shortener was already run on it by Nambu Network (now defunct). In 2009, Nambu has been so kind to publish at least major parts of the source code for their website on github. While this was definitely a great gift, it should also be noted that the code as a whole is not immediately operational and needs quite an amount of a priori adaptation. So please do not go for it if you are not familiar with the Rails framework, not willing to program and add custom code, and if an out-of-the-box solution is what you are really looking for. The software is not like that! It comprises of three Rails applications (albeit for an older version of Ruby on Rails, Rails 2 to be specific), and besides cool flash-based statistics pages, it also provides the maintenance of user accounts, including private statistics pages.

Moreover, is featuring an API and three different kinds of nifty bookmarklets. Nambu recommended to use at least one (virtual) root server to deploy At any rate, obviously requires that the Rails framework can be run on the respective server(s). To distribute incoming requests to the appropriate Rails application, Nambu suggests using HAProxy. But it is also possible to deploy on only one (virtual) root server and use e.g. Apache+Phusionpassenger, deploying the apps to sub-URIs by use of PassengerBaseURI and PassengerAppRoot in the virtual host entry of your Apache configuration file, together with appropriate rules in .htaccess files.

The Resurrection: kitten (

This feature richness is not the only reason why the former site was definitely cool enough to deserve a resurrection (read below to learn more!). So had a go at upgrading the code to a newer Rails version, and at completing and improving the material, including the adaptation of the code to the current version of the Twitter OAuth API. As for the design, we largely kept it the way it has always been (a neat, but non-responsive one), with the idea of putting the former site in a kind of “time bubble”. The refurbished URL shortener is now called kitten (

1st page of kitten

A nice feature of is the support of secret short URLs: if a so-called “privacy code”, e.g. 53cr3t, is given together with the long URL to shorten, a short URL like is created, and 53cr3t acts as a kind of password to the short URL Unlike most URL shorteners, also provides statistics about which browser and OS the visitors of the shortened links are using:

Provides detailed browser stats for every link.

To be fair: to actually make this work with, you will have to add a gem like e.g. Browser and apply some custom coding: this is necessary since the respective part of the code doing that has been removed from

URL Claiming

There is yet another ubercool feature of URL claiming. So what is this and how does it work?

Some Twitter clients such as Twitcher or Hotot allow for support and to enter one’s account in their preferences. Without the username and password it is not possible to attach URLs to one’s account. But what if a Twitter client does support, but does not allow to enter one’s credentials? Or if one decides to better not give a certain application the credentials? The solution to this is » URL Claiming«:

Anytime you share an URL on Twitter with an account that you configure with, we will see it after a while (usually within 15 minutes), and attach it to your account automatically if it is not already owned by anyone else. On, you can configure a Twitter account for URL claiming under Account > Authorizations and Account > Claim URLs.

Please have a look at the following illustrations to see how easy it actually is:

After you pressed the »Authorize« button on, you are sent over to the Twitter site to authorize your Twitter account for the kitten app:

Kitten Twitter app

As for a brief explanation what you are doing there: supports a service-specific authorization system that Twitter uses to protect your Twitter password. With this system, called OAuth, we do not need to see or store your Twitter password, ever.

At Twitter’s website you explicitly authorize to access your Twitter account, and they give us a secret code to use on your behalf. You can revoke these permissions at any time. Once you have done so, you will be redirected to the following page on

Authorized the kitten app

Under Account > Claim URLs, you can check whether URL claiming is activated now:

Claim URLs for Twitter

You are all set to go! Now for the cool stuff: suppose you do not want to put your credentials “in the wild”, i.e. you do not wish to give a Twitter client like Hotot your credentials (i.e. your user name and password): in other words you want to make sure that your credentials will not be sent over the internet every time when you submit a new tweet containing a URL.

With URL claiming, all you have to do is configure Hotot via the trim_simple API, like so (Preferences > Extensions > Hotot Short URL > Options cog):

Hotot configuration

The string to enter is: »«

Now for composing your tweet: let us say it contains an impertinently long URL:

Composing a tweet with hotot

Clicking the »Link« icon (second from the left) in the bottom tools bar clearly helps, and after a second or so your long URL gets shortened, e.g. like so:

URL Shortening with hotot

Now go for »Update«, i.e. send your tweet. And right after some fifteen minutes or so, go checking the URLs in your account: magically, it will appear there, even without having given Hotot any information about your credentials:

Succeeded in claiming the URL!

This little magic has been made possible by a service running on our infrastructure, continuously looking for new tweets containing URLs on the Twitter streams. It is only fair to note that Nambu Network did not publish the particular part of their source code managing this. Therefore, a respective service was first implemented and set up at the Labs. Needless to say that you will either need a (virtual) root server or at least a provider allowing for cron jobs to deploy such a service yourself.

The next part of our series of short articles will continue the discussion of self-hosted scripts for URL shorteners with YOURLS.