Setting up a Self-Hosted Link Shortener

Posted on • 10 min read

Tags: self-hosted

03/11/2018 - You may notice that all the images from within this post have gone "missing". I had issues with a VM migration that went slightly wrong. I'll need to manually re-create all of them... which will take a while :( The content is still here, but if you like pictures you'll be sad. Remember kids "the condition of any backup is unknown until a restore is attempted"!!

In your web surfing experience, you have probably clicked on a shortened link before. You may even click on them regularly, especially if, like me you are a frequent Twitter scroller! It's what allows a link like https:\\\short instead of https:\\\reallylonglink\thatlooks\horrible.

It's something that has become popular in the last few years especially, and it's great for marketing. You can easily pop a short link on a poster that is easy to remember and doesn't take up a lot of space on the poster itself.

I saw an example the other day on an advert on the train. It was from Facebook (about fake accounts), they had a link at the bottom to find out more, and it was a nice simple, easy to remember link, with a custom short domain:

That's the key ingredient of a short link. You need a short domain. I've seen some clever short domains out there that make use of the plethora of domain endings, one I use a lot is which is the short domain for (it's a disposable email service, very handy for when you're not sure if you want to give your real email address away!).

I've written this post to document how I went about installing my own self-hosted link shortener. I've found when I pick a title for my posts, the link can sometimes become a bit ridiculous, and when I paste that into Twitter or LinkedIn and the like, it can look messy and distract from the tweet or post. I've had the domain registered for a little while, and thought I could make use of that, jk being jake, and pr being price.

My blog is hosted on a shared hosting package, using cPanel as it's hosting control panel. So, if you are following along, unless you are also using cPanel the process is going to be slightly different for you, but it's still pretty simple. If you're technically minded it should be easy enough to translate these instructions to a similar web host.

Let's get started.

Adding an addon domain to cPanel

My blog and thus my web host package uses as its primary domain, and I want to use under my same package. In other words, I don't want to buy another hosting package just to use a link shortener!

I'm lucky because my host Jolt allows me to add an addon domain, which is exactly what it sounds like it is. Simply put, I'm allowed to add another domain to my hosting package, and have it all under one roof, but crucially that domain will act as though it's a separate website, hosted somewhere else.

So, let's add to my cPanel addon domains.

In cPanel, navigate to Addon Domains under the Domains section. You'll now need to enter the domain you wish to use for shortened links, in my case After populating the first field, the rest of the fields will auto-populate. You can leave the defaults set as they are, and I suggest you do. Once the fields are populated, click the Add Domain button.


The process isn't instant, and may take up to a minute, so be patient. All being well you'll get a helpful message back saying that the addon domain has been created. Brilliant!


Updating your addon domain's name servers

Now, we need to update the name servers for the addon domain to ensure it points to our web host. Otherwise we're not going to be able to access it.

This is going to be different depending on who your domain registrar is, but it's a simple enough thing to change on most registrars. You will need to point the domain to the same name servers you use for your main domain. You should be able to find these in your hosting control panel, or you could just check your current domain's nameservers, which is easier. So, in case your confused, I will be using the same nameservers for as I will for

Once you have them, edit the nameservers for your short domain. In my case the nameservers are and

Once you have found the section of your registrar's control panel where you can update the nameservers add your hosts nameservers in.


Once you've done that the waiting starts, it can sometimes take a few hours or longer for your nameservers to update. Keep checking your addon domain in a browser, and depending on your host you'll get something like the below come up when you try to access the domain in a browser.


We're now good to go. We've got our addon domain up and running on our host, and we can now create a MySQL database and install our link shortener of choice.

Creating a database

I've chosen an open source link shortener called YOURLS, it should do the job nicely. Before I tell you how to download it though, we may as well create our MySQL database before we go any further.

In cPanel, navigate to MySQL Databases Wizard. This is the quickest and simplest way to get a database up and running.


We'll start by giving our database a name. Let’s call it, (predictably) yourls, fill in the field and click Next Step.


Then, we need to create a user for the database. I'm going to call it yourlsuser. Make sure you generate a secure password (you can use the password generator), and click Create User when done.

Important Note: Make a note of this password (put it in a password manager), we'll need it later, and you may need it in future!


The wizard now takes us to the last step requiring input. We need to select the database user's permissions, or privileges.

You'll be presented with multiple options, which can seem a bit overwhelming. All you need to do is select ALL PRIVILEGES and click Next Step. Simple enough!


That's it, all being well the database wizard will now confirm that the database has been created and your user has been added to it.


We can now get to the fun bit, installing and playing with YOURLS.

Downloading and installing YOURLS URL Shortener

It's now time to finally download the link shortener we are going to be using. As I mentioned earlier we're going to be using an open source tool called YOURLS. (Can I just say, that despite it being a good piece of software. I keep wanting to write YOURURLS instead of YOURLS!) We'll be getting the latest release from GitHub, which you can find here. You'll want to download the .zip version for this guide, highlighted below.


It's a tiny 2.5 MB file so shouldn't take long to download, unless you’re in Antarctica or you're following this tutorial from the year 1999...

Once downloaded we will need to upload it to our host.

Within cPanel navigate to your file manager.


As we have already added the addon domain, we will need to navigate to the folder that goes by the name of your addon domain, in my case the folder. This is where you'll store anything you want associated to your addon domain.

Once you're in the folder, upload the .zip we just downloaded, and then use the file managers built in extract functionality to extract it into the folder.


I want the software to be at the root of my addon domain, otherwise my short links will look like or similar, which is not what we want. I want my links to be like

To accomplish that we just need to move everything out of the extracted YOURLS folder into the root folder.

So, after extracting the .zip go into the YOURLS-1.7.2 folder and select everything in it, and either click move, or drag and drop it into the root folder. You can now delete the now empty YOURLS-1.7.2 folder. It should look something like this:


We can now navigate into the user folder and copy config-sample.php and rename it as config.php.

Now we need to edit the config.php file. We can do this from the cPanel file manager.


You'll be faced with a fair bit of text, but it contains some options we need to configure to get up and running.

Make sure you scroll down to the $yourls_reserver_URL list for a giggle... You'd hate to have a link with one of those words automatically generated!

You can find more on what each option does in the config file here:

We need to fill in the config options with the name, user and password of the database we created earlier. Open config.php using an editor, or the built-in file manager editor and fill in the fields below replacing them with whatever you set for the database name, user and password.

You would obviously change prefix_ to whatever your cPanel prefix is (it'll possibly be your cPanel username).

 ** MySQL settings - You can get this info from your web host

/** MySQL database username */
define( 'YOURLS_DB_USER', 'prefix_DATABASE-USER-HERE' );

/** MySQL database password */

/** The name of the database for YOURLS */
define( 'YOURLS_DB_NAME', 'prefix_DATABASE-NAME-HERE' );

/** MySQL hostname.
 ** If using a non standard port, specify it like 'hostname:port', eg. 'localhost:9999' or '' */
define( 'YOURLS_DB_HOST', 'localhost' );

/** MySQL tables prefix */
define( 'YOURLS_DB_PREFIX', 'yourls_' );

You should also make sure you edit the YOURLS installation URL further down the configuration file. I've edited it to:

define( 'YOURLS_SITE', '' );

Next go to the domain address, and you should be faced with an initial screen. Click Install YOURLS.


If everything has been entered correctly you'll be informed via a few messages, as below.


You can click the YOURLS Administration Page link to login. However, before you can login, you need to create a username and password. For that we need to go back to the config file. Scroll down to line 58, and fill in something like the below. You are literally putting the username in the username field, and the password in the password field. Don't worry, the password is encrypted after saving.

/** Username(s) and password(s) allowed to access the site. Passwords either in plain text or as encrypted hashes
 ** YOURLS will auto encrypt plain text passwords in this file
 ** Read for more information */
$yourls_user_passwords = array(
	'username' => 'password',
	// 'username2' => 'password2',
	// You can have one or more 'login'=>'password' lines

Before we login, we need to add a .htaccess file. When I first installed YOURLS to the root directory (and not in its own subfolder), I had some issues because I didn't have one. When I generated a link and then clicked it I stumbled upon the error below.


It seems you need to put the below content in to your .htaccess file which should resolve the error, and properly redirect the link.

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^.*$ /yourls-loader.php [L]

More on the above here:

There's a cool little trick you can do in the .htaccess file to ensure anyone typing in just your domain, without a shortened URL at the end, is redirected to your main site. Pop the below after the # END YOURLS line in your .htaccess file. Replacing my domain with your own. Save it and then try going to your short domain only, like all being well it will redirect. It won't break your short URLs, they'll keep working. It should also hide your directory from being readily available as well.

I'm no expert on .htaccess files, so feel free to correct me in the comments if I've misunderstood something here.

<IfModule mod_rewrite.c>
RewriteRule ^/?$ [R=301,L]

The above should work like below.


Go to login with the username and password, if you've configured everything correctly you'll be able to login and start creating shortened links.



Now, it's good to use right this moment, but you may wish to add some plugins. One of the plugins that I use is called the Random-Keywords plugin, and it sets your shortened links to work like other link shortener’s out there, converting the long link to something like without this YOURLS assigns links like /a1, a2 etc. You might like that, I personally don't.

You can download the plugin here.


That's it, easy huh?! Thanks for following along, as I mention above, do feel free to let me know if you think I've written something up incorrectly, but I hope this has been a help to any of you perhaps looking to do something similar.

Keep a look out for my new short links, coming your way!

Photo by Suganth on Unsplash