How to Install YOURLS on CentOS 8 and Get Your Own URL Shortener Running
If you want a lightweight, self‑hosted link shortener that gives you full control over your URLs, YOURLS (Your Own URL Shortener) is the tool for you. In this guide we’ll walk through a clean install on CentOS 8, covering every piece of software you need and the quirks that can trip up even seasoned sysadmins.
1. Make Sure the Core Stack Is Ready
1.1 Update the System
sudo dnf update -y
Don’t skip this; a fresh kernel keeps your security patches up‑to‑date and prevents subtle library mismatches later on.
1.2 Install Apache, PHP, and MariaDB
YOURLS runs best with the LAMP stack (Linux + Apache + MySQL/MariaDB + PHP). Use these commands:
sudo dnf install httpd php php-mysqlnd mariadb-server -y
- httpd is Apache’s package name on CentOS.
- php-mysqlnd lets PHP talk to MariaDB without the older MySQL connector.
- MariaDB ships bundled with CentOS, so you won’t have to add a third‑party repo.
1.3 Start and Enable Services
sudo systemctl enable --now httpd mariadb
Running them from boot is non‑negotiable; otherwise your shortener will die every time the machine reboots.
2. Secure MariaDB
After installation, secure the database:
sudo mysql_secure_installation
- Set a strong root password.
- Remove anonymous users and test databases.
- Disallow remote root login unless you really want it.
When prompted to change the authentication plugin for root, choose mysql_native_password. YOURLS doesn’t play nice with the default caching_sha2_password.
3. Create a Database and User for YOURLS
sudo mysql -u root -p
Inside the MySQL shell:
CREATE DATABASE yourls CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; GRANT ALL PRIVILEGES ON yourls.* TO 'yourls_user'@'localhost' IDENTIFIED BY 'StrongPassword!'; FLUSH PRIVILEGES; EXIT;
Why bother? YOURLS stores all clicks and statistics in this database. Keeping it separate from other data reduces risk if you ever need to drop tables or backup.
4. Pull YOURLS into Apache
4.1 Move Into the Web Root
cd /var/www/ sudo git clone https://github.com/YOURLS/YOURLS.git yourls
If git isn’t installed, you can download a ZIP from GitHub and unzip it there.
4.2 Set Permissions
sudo chown -R apache:apache yourls
sudo find /var/www/yourls -type d -exec chmod 750 {} \;
sudo find /var/www/yourls -type f -exec chmod 640 {} \;
A common pitfall: if the permissions are too open, Apache can’t write cache files; if they’re too tight, YOURLS will choke on uploads. The apache user is the one that runs the web server, so it needs read/write access to everything but not beyond.
5. Configure YOURLS
5.1 Rename and Edit the Configuration File
cd /var/www/yourls sudo cp config-sample.php config.php
Open config.php in your editor of choice:
define( 'YOURLS_SITE', 'https://short.yourdomain.com' ); define( 'YOURLS_DB_USER', 'yourls_user'); define( 'YOURLS_DB_PASS', 'StrongPassword!'); define( 'YOURLS_DB_NAME', 'yourls');
- YOURLS_SITE should be the full URL where you want YOURLS accessible.
- The database credentials must match what we created earlier.
I’ve seen folks get tripped up by a missing trailing slash in YOURLS_SITE; it causes redirect loops that are annoying to debug.
6. Point Apache at Your Installation
Create an Apache virtual host file:
sudo tee /etc/httpd/conf.d/yourls.conf <<'EOF'
<VirtualHost *:80>
ServerName short.yourdomain.com
DocumentRoot /var/www/yourls/public
<Directory "/var/www/yourls/public">
AllowOverride All
Require all granted
</Directory>
</VirtualHost>
EOF
Then restart Apache:
sudo systemctl restart httpd
If you’re using HTTPS (recommended!), add a self‑signed certificate or use Let’s Encrypt. Just remember to change the <VirtualHost> directive to *:443 and add SSL directives.
7. Finish the Installation Through the Web Interface
Open your browser at http://short.yourdomain.com. YOURLS will detect that it hasn’t been set up yet and walk you through a quick wizard:
- Verify database connection.
- Set an admin username and password.
- Choose whether to enable public or private URLs.
After the wizard, log in with the credentials you just created. You should see the dashboard showing stats for your new short links.
8. Common Post‑Install Tweaks
| What | Why |
|---|---|
| Enable PHP error logging – add error_log = /var/log/httpd/php_error.log in /etc/php.ini | Helps catch any runtime issues you didn’t see during installation. |
| Restrict the admin area – add a .htaccess with Basic Auth to /public/yourls-admin | If you’re running YOURLS on a public server, this extra layer can stop random people from brute‑forcing your login. |
| Back up the database regularly | URLs are your content; losing them is like losing a library of links. |
I’ve seen YOURLS installations fail after a PHP update that changed default timezone settings. A quick date.timezone = UTC in php.ini usually does the trick.
9. Done!
You now have a fully functional, self‑hosted URL shortener running on CentOS 8. Keep an eye on updates to YOURLS and your underlying stack; security is a moving target but with these steps you’re already ahead of most casual users.
