YOURLS

#lang-php #shortlinks #web 

YOURLS is a set of PHP scripts that will allow you to run Your Own URL Shortener with complete control over your data, detailed stats, plugins, and more.

Note

For this guide you should be familiar with the basic concepts of

License

YOURLS is released under the MIT License. All relevant information can be found in the LICENSE file in the repository of the project.

Prerequisites

We’re using PHP in the stable version 8.1:

[isabell@stardust ~]$ uberspace tools version show php
Using 'PHP' version: '8.1'
[isabell@stardust ~]$

You’ll need your MySQL credentials. Get them with my_print_defaults:

[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$

Your website domain needs to be set up:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Remove the default page from your DocumentRoot:

[isabell@stardust ~]$ rm -f /var/www/virtual/$USER/html/nocontent.html
[isabell@stardust ~]$

Installation

To install YOURLS we clone the current version from GitHub to your DocumentRoot using Git.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/html
[isabell@stardust html]$ git clone https://github.com/YOURLS/YOURLS .
Cloning into '.'...
remote: Enumerating objects: 27, done.
[…]
[isabell@stardust ~]$

YOURLS saves all your data in a MySQL database which we have to create first. We suggest you use an additional database. In this guide we create a new database called isabell_yourls.

[isabell@stardust ~]$ mysql -e "CREATE  DATABASE ${USER}_yourls"
[isabell@stardust ~]$

Configuration

To configure YOURLS you need to setup your configuration file. Copy the sample configuration file and open it with a text editor of your choice.

[isabell@stardust ~]$ cp /var/www/virtual/$USER/html/user/config-sample.php /var/www/virtual/$USER/html/user/config.php
[isabell@stardust ~]$
Edit the following parts of your configuration file:

  • change the values of YOURLS_DB_USER, YOURLS_DB_PASS, YOURLS_DB_NAME to reflect your MySQL credentials

  • change the value of YOURLS_SITE to your previously set up domain including the protocol (in this case https://isabell.uber.space)

  • replace the value of YOURLS_COOKIEKEY with a long random string which is used to secure cookies. You can generate a string using this webservice and copy it from there.

  • setup an admin account by editing the username and password in the yourls_user_passwords variable. Don’t worry, YOURLS will hash these plain text passwords on the next login attempt. Please don’t use admin as your username and set yourself a strong password.

Save the configuration file and point your browser to your website URL and append /admin (e.g. isabell.uber.space/admin) to visit the YOURLS admin interface. On your first visit there is only one button called Install YOURLS. Click this button and the application will finish the setup.

That’s it. You can now login using your account.

Best practices

Privacy

By default YOURLS logs every visit on a shortlink with the complete IP address of the visitor. You might want to change that in regard to the GDPR.

In order to only save shortened IP addresses for your statistics you can install the plugin yourls-pseudonymize. To install the plugin clone the plugin repository to /user/plugins using Git.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/html/user/plugins
[isabell@stardust plugins]$ git clone https://github.com/ubicoo/yourls-pseudonymize
Cloning into 'yourls-pseudonymize'...
remote: Enumerating objects: 21, done.
[isabell@stardust ~]$

Last but not least you need to activate the plugin in the “Manage Plugins” area of your YOURLS admin interface.

Updates

Note

Check the update feed regularly to stay informed about the newest version.

Check YOURLS’ releases for the latest versions. If a newer version is available, you should update your installation.

To update YOURLS you can use Git to pull the newest release.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/html
[isabell@stardust html]$ git pull origin master
From https://github.com/YOURLS/YOURLS
* branch            master    -> FETCH_HEAD
[...]
[isabell@stardust ~]$

Warning

Your YOURLS instance is not updated automatically, so make sure to regularly check any update options.

Tested with YOURLS 1.9.2 and Uberspace 7.13.0, and PHP 8.1

Written by: Daniel Kratz <https://danielkratz.com>