Self-Hosted URL Shortener with YOURLS [Bit Goblin Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Self-Hosted URL Shortener with YOURLS ======

This tutorial will walk you through how to setup a URL shortener using YOURLS. Because it is a PHP-based app, you will need three things:

  * Web server to handle the HTTP requests
  * PHP interpreter to handle the application code
  * Database to store data

To handle these three requirements, we'll be using Apache as the web server, mod-php to handle the app code, and MariaDB for the database. Note that these commands are intended for a Debian system, but will also work on other OSes like Ubuntu, Red Hat/AlmaLinux, OpenSUSE, FreeBSD, and others - you'll just need to change some package names and/or file paths to match your OS.

**Note:** All of the commands shown below should be run as root, or prefixed with `sudo` to get root privileges. Some CAN be run without root, but for ease of use this guide will be assuming you're running as root.

===== Step 1: Download and "Install" YOURLS =====

The first thing you need to do to install any software is download it. Head on over to the [[https://github.com/YOURLS/YOURLS/releases|YOURLS GitHub releases page]] and download the source code ZIP file for the latest release (for reference at the time of this writing it's 1.9.1). For ease of use, you can use this command to download that ZIP file to your current directory:

<code bash>wget https://github.com/YOURLS/YOURLS/archive/refs/tags/1.9.1.zip</code>

Now we need to extract the ZIP file and put it in place so that Apache can read it. I tend to follow the [[https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard|Linux FSH guidelines]], so let's create a directory under `/srv/` for websites, and then move into it.

<code bash>mkdir /srv/www; cd /srv/www</code>

Then extract that YOURLS ZIP file that you downloaded a moment ago:

<code bash>unzip ~/1.9.1.zip</code>

**Note:** if the above command fails, try installing the unzip command with ''%%apt install -y unzip%%'', then try the unzip command again.

If all goes well, you should now have a directory located at `/srv/www/YOURLS-1.9.1` that has the YOURLS source code and assets in it. The next thing we need to do is to configure YOURLS with your info. `cd YOURLS-1.9.1` to dive into the source directory, and then we need to copy the sample configuration file into the proper place:

<code bash>cp user/config-sample.php user/config.php</code>

And then open that new file up in your favorite text-editor, for example with VIM:

<code bash>vim user/config.php</code>

You'll be presented with a bunch of configuration options (using PHP code syntax) that you can modify to your heart's content, but there are a few main options that I want to point out that you'll want to change. We'll also touch on the database configuration later on when we're setting up MariaDB.

''%%YOURLS_SITE%%'' - This is the web address of your site. You'll want to set this to how you want people to be accessing your site. For example, the Bit Goblin shortener's address is u.bitgoblin.tech, so this value is set to ''%%https://u.bitgoblin.tech%%''.

''%%YOURLS_UNIQUE_URLS%%'' - This determines whether you allow multiple short links to the same original site address. The intended use of your URL shortener will likely determine whether you want this to be true or false, e.g. if you want people to enter their own links to shorten, regardless of whether it's already present.

''%%YOURLS_PRIVATE%%'' - You'll likely want to keep this set to ''%%true%%'', but this setting determines whether or not you want the admin interface to be locked behind user credentials. SETTING THIS TO FALSE IS NOT RECOMMENDED FOR A PUBLIC SITE!

''%%YOURLS_COOKIEKEY%%'' - This value is used in encrypting browser cookies. This doesn't need to remembered/saved anywhere, just make it long and random. You can head on over to [[https://www.grc.com/passwords.htm|GRC's password generator]] and grab any sizeable chunk of any three of the randomly generated passwords and paste it in for this value. I'd recommend the middle one with 63 ASCII characters, but this'll be dealer's choice.

''%%$yourls_user_passwords%%'' - This is a PHP array/map with at username and password mappings. You'll want to create yourself a user here, so inside the array change the ''%%'username' => 'password'%%'' mapping to the credentials you want for your admin user. For example, if you want the username "admin" and password of "supersecretpassword", it would look like ''%%'admin' => 'supersecretpassword'%%''.

There are some more configuration options to look over if you please, but this is all we need to look at for now. Go ahead and save and close the config file, and get ready to install Apache.

===== Step 2: Install Apache =====

The second thing we need to do is to install Apache to handle HTTP requests to this server. Thankfully, installing Apache with a base configuration is really easy on most Linux distributions, and Debian is no different. Simply run the command below to install Apache:

<code bash>apt install -y apache2</code>

And you can check the status of the service like so:

<code bash>systemctl status apache2</code>

If all went well, then Apache is installed and running with a default configuration. Simply open up a web browser, and enter %%"http://"%% plus your server's IP address, like ''%%http://192.168.1.50%%'', and you should be met with a page that looks something like this:

{{ wiki:debian-apache-test-page.png?direct&400 |}}

But of course, this isn't YOURLS, and the page we did get is kinda useless! Now we need to configure Apache to use/display your YOURLS site. Open up the Apache default site config:

<code bash>vim /etc/apache2/sites-available/000-default.conf</code>

In the VirtualHost, there should be a line for ''%%DocumentRoot ...%%''. Change it to read:

<code>DocumentRoot /srv/www/YOURLS-1.9.1</code>

Then save and close the file. YOURLS also makes use of the Apache rewrite module, so we need to enable it with:

<code bash>a2enmod rewrite</code>

Then to load the updated configuration, restart the Apache service:

<code bash>systemctl restart apache2</code>

And if you refresh your web browser, it should now be showing something else...

{{ wiki:yourls-php-error.png?direct&600 |}}

It's just a bunch of code! That's not right... Well, by default Apache has no idea what to do with PHP code, so it's just serving the PHP files as a static plain text file.

===== Step 3: Install PHP =====

To get PHP working with Apache, we need to both install PHP and the Apache PHP module to link it all together. To do that, run:

<code bash>apt install -y php libapache2-mod-php</code>

Then enable the newly installed mod-php for Apache like so:

<code bash>a2enmod php7.4</code>

**Note:** it's usually just ''%%a2enmod php%%'', but Debian has the PHP module includes labeled per the PHP version, so as to let you include multiple different PHP versions if you choose.

And again, restart Apache to reload the config:

<code bash>systemctl restart apache2</code>

One last thing before you open up your web browser is you will want to make the www-data user the owner of the website files. This is so it can install the app properly (mainly putting in place the ''%%.htaccess%%'' file for routing), and encrypting your user password(s).

<code bash>chown -R www-data /srv/www/YOURLS-1.9.1</code>

Now open up your web browser again and go to the same address as before and prepend "/admin", e.g. ''%%http://192.168.1.50/admin/%%'' and you should be greeted with a YOURLS error page.

{{ wiki:yourls-db-error.png?direct&600 |}}

This is normal. YOURLS requires a database to run, and we haven't configured the database yet (remember I said that we'd get to this later?), so let's get to it!

===== Step 4: Configure a Database with MySQL =====

Finally, we just need to setup a database so YOURLS has a way to store information. As far as I can tell, YOURLS only supports MySQL/MariaDB for the backend database. Some may hate this, but to me this is perfectly fine. To install MariaDB, run:

<code bash>apt install -y mariadb-server</code>

And you can check the status of the service with:

<code bash>systemctl status mariadb</code>

While not strictly required, it's recommended to run the ''%%mysql_secure_installation%%'' script to tighten up from the default configuration. You can accept all of the default values, except I'd skip setting the root password since by default it uses Unix socket authentication and you need to be the root account to login with it.

Now that MariaDB is ready to roll, let's login and create a database for YOURLS.

<code bash>mysql -u root</code>

Create a new database:

<code sql>CREATE DATABASE yourls;</code>

Create a new user for the database:

<code sql>CREATE USER 'yourls'@'localhost' IDENTIFIED BY 'secretpassword';</code>

Grant all privileges on the YOURLS database to the new user:

<code sql> GRANT ALL PRIVILEGES ON yourls.* TO 'yourls'@'localhost';</code>

And finally flush the database privileges. This is important so permission changes take effect!

<code sql>FLUSH PRIVILEGES;</code>

And now exit with ''%%exit%%''.

With our database configured, let's head back to that ''%%config.php%%'' file:

<code bash>vim /srv/www/YOURLS-1.9.1/user/config.php</code>

And towards the top of the file should be several settings for the database configuration. Change the settings to match the following:

<code>
YOURLS_DB_USER => yourls
YOURLS_DB_PASS => secretpassword
YOURLS_DB_NAME => yourls
YOURLS_DB_HOST => localhost
</code>

Now save and close the file, then refresh your browser. If all goes well, you should be at the YOURLS login page!

{{ wiki:yourls-login.png?direct&600 |}}

Enter your credentials, then you should be met with the YOURLS admin interface.

{{ wiki:yourls-admin.png?direct&600 |}}

At this point, your YOURLS installation is complete, and you can start shortening URLS!

===== Step 5: Finishing Touches =====

Now that YOURLS is running, there is one last set of tweaks I'd recommend to make your YOURLS experience better. Head on over to the Plugins page via the "Manage Plugins" link at the top of the page. Then activate the ''%%Random ShortURLS%%'' and ''%%Allow Hyphens in Short URLS%%'' plugins - these two plugins do exactly what their names say: generate random URL slugs by default for the shortened URLS (these can be edited), and allow the hyphen character to be used in the URL slugs. Simple enough, and makes the experience slightly more streamlined and allows for more short URL possiblities.

{{ wiki:yourls-plugins.png?direct&600 |}}

You can also enable the ''%%Random Backgrounds%%'' plugin for a prettier interface. It's nothing huge, but I kinda like the admin interface a little bit more with the random backgrounds. This one is up to you if you want it.

Have fun!