YOURLS: Your Self-Hosting Setup and Management Guide

YOURLS (Your Own URL Shortener) is a self-hosted URL shortening application designed for developers and tech enthusiasts who need full control over their data. It allows you to create custom short links, manage them efficiently, and even tap into advanced features like API integrations. Being lightweight, highly customizable, and open-source, YOURLS is an excellent choice for those looking to self-host URL shortening services without relying on third-party providers. This guide covers everything from installation to advanced configurations so you can deploy, secure, and manage your own YOURLS instance.

Installing YOURLS

📦 Docker/Docker Compose Setup

Docker simplifies the deployment of YOURLS by encapsulating everything in containers. Here’s how you can set it up:

Create a docker-compose.yml file:


version: '3.8'

services:

yourls:

image: yourls:latest

container_name: yourls

ports:

- "8080:80"

environment:

YOURLS_SITE: "https://example.com"

YOURLS_USER: "admin"

YOURLS_PASS: "securepassword"

volumes:

- ./data:/var/www/html/user

restart: unless-stopped

Deploy the YOURLS container:


docker-compose up -d

Verify that YOURLS is running:


docker ps

Access YOURLS in your browser at http://<your-server-ip>:8080.

🚀 Manual Installation

To install YOURLS manually on a Linux server, follow these steps:

Install dependencies:


sudo apt update

sudo apt install -y apache2 php php-mysql unzip curl

Download the YOURLS source code:


curl -L https://github.com/YOURLS/YOURLS/archive/refs/heads/master.zip -o yourls.zip

unzip yourls.zip

sudo mv YOURLS-master /var/www/html/yourls

Configure directory permissions:


sudo chown -R www-data:www-data /var/www/html/yourls

sudo chmod -R 755 /var/www/html/yourls

Set up YOURLS by renaming the sample config file:


cd /var/www/html/yourls/user

cp config-sample.php config.php

Edit config.php to match your server setup:


nano config.php

Update fields such as database credentials, YOURLS URL, admin username, and password.

Restart Apache to serve YOURLS:


sudo systemctl restart apache2

YOURLS will now be accessible via http://<your-server-ip>/yourls.

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

Set up Nginx to serve YOURLS and handle incoming HTTPS traffic:

Create an Nginx server block:


sudo nano /etc/nginx/sites-available/yourls

Add the following configuration:


server {

listen 80;

server_name example.com;

location / {

proxy_pass http://127.0.0.1:8080;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

}

}

Enable the configuration:


sudo ln -s /etc/nginx/sites-available/yourls /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx

🔒 SSL/TLS Setup

Secure your YOURLS instance with Let's Encrypt:

Install Certbot:


sudo apt install certbot python3-certbot-nginx

Obtain and apply a certificate:


sudo certbot --nginx -d example.com

Verify automatic renewal:


sudo systemctl enable certbot.timer

🛠️ Testing and Reloading Nginx

Ensure the configuration works properly:


sudo nginx -t

sudo systemctl reload nginx

Logging and Debugging YOURLS

🗃️ Enabling Debug Logs

Enable debug mode for YOURLS in the config.php file:


define( 'YOURLS_DEBUG', true );

📄 Viewing Logs

For Docker:


docker logs yourls

For manual installations, check the web server logs:


tail -f /var/log/apache2/error.log

🛠️ Troubleshooting Common Issues

For database errors, verify credentials in config.php. For 404 issues, double-check your Nginx or Apache configuration.

📤 Exporting Logs

Send logs to an external system like ELK Stack using Filebeat or a similar tool:


sudo apt install filebeat

sudo filebeat setup

sudo systemctl start filebeat

Backup and Restore

🗂️ File-Based Backups

Backup YOURLS files:


tar -czvf yourls_backup.tar.gz /var/www/html/yourls

🔄 Database Backups

Export the YOURLS database:


mysqldump -u root -p yourls_db > yourls_db_backup.sql

Restore the database:


mysql -u root -p yourls_db < yourls_db_backup.sql

📅 Automated Backup Scripts

Schedule periodic backups using cron:


crontab -e

Add this line:


0 2 * * * tar -czvf /backups/yourls_$(date +\%F).tar.gz /var/www/html/yourls

Updating and Upgrading YOURLS

⬆️ Updating Docker Images

Update YOURLS to the latest version with Docker:


docker-compose down

docker-compose pull

docker-compose up -d

🛠️ Manual Updates

To manually update YOURLS:


cd /var/www/html/yourls

git pull origin master

🔍 Checking for Updates

Monitor YOURLS releases on GitHub:


curl -s https://api.github.com/repos/YOURLS/YOURLS/releases/latest | grep tag_name

Leveraging YOURLS’s Unique Features

🔧 Enabling APIs

Enable YOURLS APIs by ensuring the following line is in config.php:


define('YOURLS_API', true);

Test the API with curl:


curl -u admin:securepassword "https://example.com/yourls-api.php?signature=YOUR_SIGNATURE&action=shorturl&url=https://example.com&format=json"

🌟 Advanced Configurations

Customize YOURLS with plugins:

Install plugins by copying them to the user/plugins directory.
Activate plugins in the YOURLS admin panel.

For example, to add Google Analytics tracking, upload the appropriate plugin and enable it.

Wrapping Up

This guide demonstrated how to deploy, configure, and manage YOURLS effectively. By following these steps, you can host your own URL shortener with full control over its functionality and data. Start experimenting with YOURLS’s APIs and plugins to unlock its full potential, and extend your deployment with additional features tailored to your needs.