Hosting your own URL shortener with YOURLS, Azure Web Site and WebMatrix

For a couple years now, I’ve been paying for a private-label URL-shortening service.  I’ve amassed hundreds of links, and don’t want to lose any of the shortcuts, but the cost has gone up with no change in features.  I would love to have better metrics, and certainly a lower cost.  Having a small Azure benefit gives me a level of free hosting with an Azure website.  I hunted around and found several open source URL shorteners.  I decided on using YOURLS, a PHP-based application with all the features I want and then some (nice charts, plugins, social sharing, an API and bookmarklets).  Plus, it looked insanely easy to install.  Here’s how I set up YOURLS on Azure (this blog post took longer and is more difficult to read than the actual process, it was that easy).  There are a couple paths you can follow here, yours may differ from mine since I already had some existing services set up.

Step 1: MySQL on Azure

YOURLS uses MySQL as its database.  There are two primary ways you can host MySQL on Azure:

  • ClearDB offers hosted MySQL databases on Azure, with a 20 MB developer instance for free.  This is plenty to play around with, but if you want more you can.  There are two ways to set up CleaDB on Azure: How to Create a MySQL Database in Windows Azure.
  • Spin up a VM (Linux or Windows) and host a MySQL instance on it.  This is probably the more expensive option, but gives you the utmost control.  If you wanted to use this VM to host your YOURLS, you could, but that’s another blog post.

I already had my developer instance set up from an earlier WordPress experiment.  I created this instance as a linked resource for Windows Azure Web Site previously, which is an easy way to get started, but limits you to the 20 MB limit.

Either way, follow one of the sets of instructions at to get started.

If you’re sharing a MySQL database, by default the Yourls tables are created with yourls_ prefix, so you can separate new tables from existing ones.

Step 2: Creating the Web Site

As with the MySQL database, you can do this in one of two ways.  If you have already followed, or plan to follow, the instructions for creating a MySQL database as a linked resource, use that and skip this step.  In that process, you’ll create a site in the Azure portal, then create a CleaDB MySQL instance linked to the site.

If you have a existing MySQL database, but need to create the website, you can create the site from within WebMatrix 3, which is what I did (if you don’t have WebMatrix 3, you will need to update to the latest version).

From the start screen, New >> Empty Site starts the process.


The next step is to find a unique name for your site, and a location to host it.  At this step you’re configuring the long name for your site.  Later you can configure a custom URL for your website.



A local and remote site are created




At this point, you’re read to start working.  You’ll be working in a local version of your website, not directly in the website.

Step 3: Installing and Configuring YOURLS

To get started this way, download the most recent version from (cloning and publishing via Git will be discussed in another post).  Unzip the download into the folder for the website created above.

Configuration options are explained at  The main ones to configure are:

  2. YOURLS_DB_PASS (remember this will be stored in plain text)
  5. YOURLS_DB_PREFIX (this is how you can separate YOURLS tables from any others in the same MySQL database)
  6. YOURLS_SITE (use the temporary URL until DNS propagates)
  7. YOURLS_COOKIEKEY (generate at
  8. $yourls_user_passwords (this is how you’ll log into the admin portal, you can encrypt these per

Do not put the config file in a publicly available location!  You have secrets in this file, make sure it stays private.

In order to view admin pages, you’ll also need to add a web.config to the root folder of your YOURLS site; see for a sample file.

Step 4: Publishing to Azure and Installing Database Tables

If you used WebMatrix to create your Azure Web Site, all you need to do now is click Publish and your files will be transferred automatically.  If you created your database and site via the Azure Portal, you’ll be prompted to either choose an existing Azure Web Site, use WebDeploy, or manually configure FTP.  This is a one-time configuration—every subsequent time you can just hit Publish.

After the site is deployed, there is a one time installation.  Simply go to http://<yoursite>, log in with the credentials you saved in the config file, and follow whatever prompts you’re given.

Step 5: Custom URL on Azure

Custom URLs for Azure Web Sites are not technically free, but you can apply Azure credits via an MSDN subscription (which I do) or pony up for a paid subscription.  Instructions for configuring a custom domain name for an Azure Web Site are at

You’ll need to have custom DNS for your site, usually this is done by using your registrar’s nameservers and custom DNS settings.  If your registrar doesn’t offer such a service, look into a service like  You’ll need to configure both a CNAME and an A record.  Do not forward your domain name.  After you configure your DNS, it’ll take a day or so to propagate completely.  Once the DNS is propagated, you’ll need to edit the config file and set the YOURLS_SITE to the custom domain name and republish.

Step 6: Track those clicks!

You should be fully running, you can extend YOURLS with some of the plugins found at

Happy shortening!