What do you think? Discuss, post comments, or ask questions at the end of this article [More about me]

Below is a guide to installing yourls, a url shortening application you can run from your server.  This guide is for ubuntu 16.04 server and covers some issues I ran into when setting up yourls on my server (accessed at https://url.jaytaala.com).  This guide has a few differences from others around and covers setting up yourls on it's own subdomain (e.g url.jaytaala.com) rather than a context (e.g. jaytaala.com/url).

This guide assumes you have a working LAMP server.

Guide

We'll cover the following steps:

  1. unpack yourls files;
  2. setup yourls mysql database;
  3. create vhost for your yourls install (and enable .htaccess for that vhost);
  4. extra security to disable file viewing on yourls sub-folders.

Unpacking yourls

Let's first unpack yourls to an appropriate location on our server.  I've chosen to install to /var/www/yourls.

You can get the required yourls release from https://github.com/YOURLS/YOURLS/releases.  Here I'll download the tar.gz file directly to a folder on my server, move files into place (remove now empty YOURLS folder):

sudo mkdir /var/www/yourls
cd /var/www/yourls
sudo wget https://github.com/YOURLS/YOURLS/archive/1.7.2.tar.gz

We'll now need to unpack and put the files into place:

sudo tar -xzf 1.7.2.tar.gz
sudo mv YOURLS-1.7.2/* .
sudo rm -r YOURLS-1.7.2/

Now, that we have our files in place, let's move on and setup a mysql database for yourls.

yourls mysql database

I'm assuming you already have mysql setup on your server and have secured it and created a root password.

Let's login as root in mysql console and create the the necessary database and a user that will access said database:

mysql -uroot -p

Once logged into mysql console, run the following:

create database yourls;
grant all privileges on yourls.* TO "yourlsuser"@"localhost" identified by "<ADD-SECURE-PASSWORD-HERE>";
flush privileges;
exit;

Modify config.php with the mysql details above

We need to now modify the yourls config.php with the mysql details we created above:

sudo cp /var/www/yourls/user/config-sample.php /var/www/yourls/user/config.php
sudo nano /var/www/yourls/user/config.php

Modify the file in nano as appropriate.  See yourls' configuration page for more information.

Create apache vhost for yourls

We're now ready to setup our virtual host for access.  I'm assuming you have a reverse proxy setup such as outlined here.

Let's create an apache .conf file for yourls with nano:

sudo nano /etc/apache2/sites-available/yourls.conf

Now modify and paste something like below:

<VirtualHost *:443>
    ServerName url.example.com
    DocumentRoot /var/www/yourls

    <Directory /var/www/yourls>
        AllowOverride All
    </Directory>

    # Your SSL certificate information for this sub-domain can go here.
    # If you use certbot-auto, it will automatically add it here if you use the --apache flag, e.g.:
    # sudo certbot-auto --apache
</VirtualHost>

<VirtualHost *:80>
    ServerName url.example.com
    Redirect Permanent / https://url.example.com/
</VirtualHost>

Note that the <Directory... > directive allows yourls to function by enabling .htaccess to the folder.

Once we've created said virtual host, let's enable it:

cd /etc/apache2/sites-available
sudo a2ensite yourls.conf
sudo service apache2 reload

It's worth nothing here that you should now setup SSL certs in yourls.conf.  If you use the excellent certbot-auto you can simply do

sudo certbot-auto --apache

and follow the instructions.  See here for more information.

We now should create the .htaccess file that yourls uses to do it's magic:

sudo nano /var/www/yourls/.htaccess

and paste the following:

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

Acessing admin page

Once you've done the above, you should be able to access the admin page at <subdomain>.<domain>.com/admin.  For example:

https://url.example.com/admin

Disable file viewing on your url.example.com sub-domain

Since we'rve created a sub-domain and only put yourls in it - visiting said sub-domain will display the list of files therein (by default).  This is usually not what is wanted.

To overcome this, we can create a index.html file to place in the documentroot (e.g. /var/www/yourls).  Your index.html file can be a blank file - however I took 10 minutes to create a simple page that looks (fairly?) nice.  See https://url.jaytaala.com  for an example.

Bonus: disable file viewing for yourls sub-folders

Yourls uses a redirect to stop viewing several sub-folders that may contain sensitive information.  It does not do this for all sub-folders however, for example:

/var/www/yourls/css
/var/www/yourls/images
/var/www/yourls/includes
/var/www/yourls/js

This isn't intrinsically bad however as these folders do not contain any sensitive info.

However, I prefer that anonymous internet users don't have the ability to view said folder contents (just my preference).  To do this we'll simply copy the redirecting index.html to the above folders:

sudo cp /var/www/yourls/user/index.html /var/www/yourls/css
sudo cp /var/www/yourls/user/index.html /var/www/yourls/images
sudo cp /var/www/yourls/user/index.html /var/www/yourls/includes
sudo cp /var/www/yourls/user/index.html /var/www/yourls/js

File permissions

Once you've setup your yourls folder I prefer to lock permissions down and make sure folder owner is root:

sudo chown -R root:root /var/www/yourls
sudo chmod -R 755 /var/www/yourls

References

  1. https://code.tutsplus.com/tutorials/build-your-own-url-shortener-with-yourls--cms-22638
  2. https://www.digitalocean.com/community/tutorials/how-to-install-linux-apache-mysql-php-lamp-stack-on-ubuntu-16-04
  3. https://github.com/YOURLS/YOURLS/releases