Install YOURLS: Your Own URL Shortener on a LEMP Server

YOURLS (Your Own URL Shortener) is a small, mature PHP application for running branded short links on your own domain. It includes click statistics, custom keywords, bookmarklets, a simple admin panel, an API, and a big plugin ecosystem. It runs on any standard PHP and MySQL host, so it fits right next to a WordPress site on the same LEMP server.

API-first alternative with richer analytics: Shlink.

Requirements

• A LEMP or LAMP server: PHP 8.x with mysqli (or pdo_mysql), plus MySQL or MariaDB. See Nginx with PHP-FPM.
• A short domain or subdomain (for example go.example.com).
• Very small resources: it runs fine on the smallest VPS.

Create the database

CREATE DATABASE yourls CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'yourls'@'localhost' IDENTIFIED BY 'strong-password';
GRANT ALL PRIVILEGES ON yourls.* TO 'yourls'@'localhost';
FLUSH PRIVILEGES;

See MySQL users and permissions.

Download and configure

cd /var/www
sudo git clone https://github.com/YOURLS/YOURLS.git go.example.com
cd go.example.com
sudo cp user/config-sample.php user/config.php

Edit user/config.php:

define( 'YOURLS_DB_USER', 'yourls' );
define( 'YOURLS_DB_PASS', 'strong-password' );
define( 'YOURLS_DB_NAME', 'yourls' );
define( 'YOURLS_DB_HOST', 'localhost' );
define( 'YOURLS_SITE', 'https://go.example.com' );     // no trailing slash
define( 'YOURLS_COOKIEKEY', '<long random string>' );
define( 'YOURLS_PRIVATE', true );                        // only logged-in users can create links
$yourls_user_passwords = [
    'admin' => 'a-strong-password',                      // hashed automatically on first login
];
define( 'YOURLS_URL_CONVERT', 36 );                      // 36 = 0-9a-z, 62 = also A-Z

sudo chown -R www-data:www-data /var/www/go.example.com
sudo chmod 640 user/config.php

YOURLS hashes the plain-text passwords in config.php automatically, which is why the web server user needs write access to that file at first.

Nginx configuration

YOURLS needs every unknown path routed to yourls-loader.php:

server {
    server_name go.example.com;
    root /var/www/go.example.com;
    index index.php;

    location / {
        try_files $uri $uri/ /yourls-loader.php$is_args$args;
    }
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
    location ~ /user/config\.php { deny all; }
    # listen 443 ssl; certbot --nginx -d go.example.com
}

On Apache, YOURLS creates the .htaccess rewrite rules during install. See Let’s Encrypt.

Install

Visit https://go.example.com/admin/, and click Install. YOURLS creates its tables. Then log in with the user from config.php.

Using it

• Shorten links in the admin panel, with a custom keyword (go.example.com/sale) or an auto-generated one.
• Add + to any short URL (go.example.com/sale+) to see its statistics: clicks over time, referrers and countries.
• Bookmarklets let you shorten the current page in one click.

API

Generate a signature token (Admin → Tools) to use the API without sending your password:

curl "https://go.example.com/yourls-api.php?signature=<token>&action=shorturl&format=json&url=https://example.com/docs&keyword=docs"

Other actions: expand, url-stats, stats.

Plugins worth knowing

YOURLS has hundreds of plugins (in user/plugins/, activated in the admin):

• QR codes for short links.
• Change error messages or redirect the root domain to your main site.
• Spam protection (if public mode is on), and Google Safe Browsing checks.
• Two-factor authentication and LDAP login plugins.

Security

• Keep YOURLS_PRIVATE true unless you want a public shortener. Public shorteners get abused for phishing and spam immediately, which can get your domain blocklisted and your server reported. See abuse handling.
• Use a strong admin password, HTTPS, and Fail2ban on /admin/. See Fail2ban.
• Keep YOURLS updated (git pull to a new release tag), and update plugins.

Backups

Back up the MySQL database and user/ (config and plugins). See mysqldump.

Quick reference

Item	Value
Config	user/config.php
Admin	/admin/
Stats for a link	add + to the short URL
API	/yourls-api.php with signature
Private mode	YOURLS_PRIVATE = true

Related: Shlink and Nginx server blocks.

• Self-Hosting
• PHP
• Marketing