Learn how to install and configure YOURLS, a self-hosted URL shortener, on Ubuntu 24.04 using Nginx.
If we want complete control over our branded short links, analytics, and privacy, deploying our own URL shortener is the way to go. YOURLS (Your Own URL Shortener) is a popular, open-source solution that is easy to set up and works great for businesses, teams, and individual creators. In this guide, we’ll walk through installing and configuring YOURLS on Ubuntu 24.04 with Nginx, so we can create and manage short URLs on our own infrastructure.
What is YOURLS?
YOURLS stands for “Your Own URL Shortener.” It’s a free, open-source PHP application that allows us to run our own short link service, similar to Bitly or TinyURL, but with complete control. YOURLS supports custom aliases, detailed analytics, bookmarklets, plugins, and an admin interface for managing our links. Running YOURLS on our own server means our data is private and branding is 100% ours.
Prerequisites
Before we start, let’s ensure we have:
- A Ubuntu 24.04 dedicated server or KVM VPS.
- A domain name (e.g., links.example.com)
- SSH access to the server
- Root or sudo privileges
How to Deploy a YOURLS Self-Hosted URL Shortener on Ubuntu 24.04 with Nginx (Step-by-Step Guide)
Step 1: Update System Packages
First, let’s make sure our system is up to date:
sudo apt update && sudo apt upgrade -y
Step 2: Install Nginx Web Server
Nginx is lightweight, fast, and reliable—ideal for serving PHP applications.
sudo apt install nginx -y
Enable and start Nginx:
sudo systemctl enable nginx
sudo systemctl start nginx
Step 3: Install PHP and Extensions
YOURLS requires PHP (8.1+ recommended) and some extensions. Let’s install them:
sudo apt install php-fpm php-mysql php-curl php-mbstring php-xml php-zip unzip -y
Step 4: Install and Secure MariaDB (MySQL)
YOURLS stores data in MySQL or MariaDB. We’ll use MariaDB:
sudo apt install mariadb-server mariadb-client -y
Secure the installation:
sudo mysql_secure_installation
Follow the prompts to set a root password and remove insecure defaults.
Step 5: Create a Database and User for YOURLS
Let’s create a dedicated database and user. Access MariaDB:
sudo mysql -u root -p
Then run:
CREATE DATABASE yourls_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'yourls_user'@'localhost' IDENTIFIED BY 'strongpassword';
GRANT ALL PRIVILEGES ON yourls_db.* TO 'yourls_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
Tip: Replace strongpassword with a secure password.
Step 6: Download YOURLS
Let’s place YOURLS in our web directory:
cd /var/www/
sudo wget https://github.com/YOURLS/YOURLS/archive/refs/heads/master.zip
sudo unzip master.zip
sudo mv YOURLS-master yourls
sudo chown -R www-data:www-data yourls
Step 7: Configure YOURLS
Rename and edit the config file:
cd /var/www/yourls/user
sudo cp config-sample.php config.php
sudo nano config.php
Update these lines in config.php:
define( 'YOURLS_DB_USER', 'yourls_user' );
define( 'YOURLS_DB_PASS', 'strongpassword' );
define( 'YOURLS_DB_NAME', 'yourls_db' );
define( 'YOURLS_DB_HOST', 'localhost' );
define( 'YOURLS_SITE', 'https://links.example.com' );
define( 'YOURLS_HOURS_OFFSET', '+5:30' ); // Set your timezone
// Set your admin credentials
$yourls_user_passwords = array(
'admin' => 'choose-a-very-strong-password',
);
Tip: Use strong passwords and adjust YOURLS_SITE to match our domain.
Step 8: Configure Nginx for YOURLS
Let’s create a new Nginx server block:
sudo nano /etc/nginx/sites-available/yourls
Add this config (replace links.example.com with our domain):
server {
listen 80;
server_name links.example.com;
root /var/www/yourls;
index index.php index.html index.htm;
access_log /var/log/nginx/yourls_access.log;
error_log /var/log/nginx/yourls_error.log;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.3-fpm.sock; # Adjust if using a different PHP version
}
location ~ /\.ht {
deny all;
}
}
Enable the config and reload Nginx:
sudo ln -s /etc/nginx/sites-available/yourls /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
Step 9: Install SSL with Let’s Encrypt (Recommended)
For secure links, set up SSL using Certbot:
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d links.example.com
Follow prompts to enable HTTPS.
Step 10: Finalize YOURLS Installation
Open our domain (e.g., https://links.example.com/admin) in a browser.
- The YOURLS installer should appear.
- Follow the on-screen steps to complete the setup.
Once finished, we can log in to the admin dashboard, start creating short URLs, and track analytics.
Step 11: Secure and Maintain Our YOURLS Instance
- Keep Ubuntu, Nginx, PHP, and YOURLS updated regularly.
- Use strong admin passwords.
- Regularly back up the database.
- Limit admin access by IP if possible for extra security.
Benefits of Running Our Own YOURLS Shortener
- Brand Control: Every short link carries our domain.
- Privacy: Data stays with us.
- Custom Analytics: Know exactly how our links are performing.
- Extendable: YOURLS supports plugins and API integrations.
Conclusion
Setting up our own YOURLS URL shortener on Ubuntu 24.04 with Nginx gives us full control over short links, data, and branding. This setup is reliable, scalable, and secure—ideal for creators, businesses, or tech-savvy teams. With this guide, we’re empowered to build and manage our own powerful URL shortener without relying on third-party platforms.
