Operating System CentOS

How to Install YOURLS on AlmaLinux 9 or Rocky Linux 9

Set up your own URL shortener with YOURLS on AlmaLinux 9 or Rocky Linux 9 using Apache, PHP 8.3 and MariaDB.

YOURLS (Your Own URL Shortener) is a small PHP application that turns a domain you own into a private link shortener with click statistics, an API and plugins. This guide installs the current YOURLS 1.10 series on AlmaLinux 9 or Rocky Linux 9 with Apache, PHP-FPM and MariaDB, and leaves you with a working admin area at https://example.com/admin/. The commands are the same on CentOS Stream 9.

CentOS 7 reached end of life in June 2024 and no longer receives security updates, and its PHP 5.4 cannot run YOURLS anyway: since version 1.10 the project requires PHP 8.1 or newer. The RHEL 9 family is the practical replacement.

Requirements

  • A server running AlmaLinux 9 or Rocky Linux 9 and a user with sudo rights.
  • A (preferably short) domain whose DNS A record points at the server; the examples use example.com.
  • What YOURLS itself asks for: Apache 2.4 or newer with mod_rewrite, PHP 8.1 or newer, and MySQL 5.5+ or MariaDB 10.0+. The PHP cURL extension is needed if you use the API. HTTPS is recommended.

Install Apache, PHP and MariaDB

Update the system, then enable the PHP 8.3 module stream. Without this step the default AppStream packages install PHP 8.0, which is too old.

sudo dnf -y update
sudo dnf module list php
sudo dnf -y module enable php:8.3

Install the web server, PHP with the extensions YOURLS uses, the database server and a few tools:

sudo dnf -y install httpd php php-fpm php-mysqlnd php-mbstring php-xml mariadb-server tar policycoreutils-python-utils

Start the services and enable them at boot:

sudo systemctl enable --now httpd php-fpm mariadb

Open the web ports in firewalld:

sudo firewall-cmd --permanent --add-service=http --add-service=https
sudo firewall-cmd --reload

Create the database

Secure the MariaDB installation (set a root password policy, remove anonymous users and the test database), then create a database and a dedicated user:

sudo mariadb-secure-installation
sudo mariadb
CREATE DATABASE yourls CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'yourls'@'localhost' IDENTIFIED BY 'use-a-strong-password';
GRANT ALL PRIVILEGES ON yourls.* TO 'yourls'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Download YOURLS

Releases are published on the project's GitHub releases page. Version 1.10.6 was the latest at the time of writing; check the page and adjust the version number if a newer one exists.

cd /tmp
curl -fLO https://github.com/YOURLS/YOURLS/archive/refs/tags/1.10.6.tar.gz
sudo mkdir -p /var/www/yourls
sudo tar -xzf 1.10.6.tar.gz -C /var/www/yourls --strip-components=1

Configure YOURLS

Copy the sample configuration and generate a random string for the cookie key:

cd /var/www/yourls
sudo cp user/config-sample.php user/config.php
openssl rand -base64 48
sudo nano user/config.php

Set at least the following values. YOURLS_SITE must be lowercase, without a trailing slash, and must be exactly the address you type in the browser (with or without www).

define( 'YOURLS_DB_USER', 'yourls' );
define( 'YOURLS_DB_PASS', 'use-a-strong-password' );
define( 'YOURLS_DB_NAME', 'yourls' );
define( 'YOURLS_DB_HOST', 'localhost' );
define( 'YOURLS_DB_PREFIX', 'yourls_' );

define( 'YOURLS_SITE', 'https://example.com' );
define( 'YOURLS_PRIVATE', true );
define( 'YOURLS_COOKIEKEY', 'paste-the-random-string-here' );

$yourls_user_passwords = [
    'deploy' => 'choose-an-admin-password',
];

The password is entered in plain text; YOURLS replaces it with a hash in the file the first time it runs, which is why the web server needs write access to user/config.php for now.

Next create the rewrite rules. YOURLS tries to write this file itself, but creating it by hand avoids giving Apache write access to the whole directory:

sudo nano /var/www/yourls/.htaccess
# BEGIN YOURLS
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^.*$ /yourls-loader.php [L]
</IfModule>
# END YOURLS

Set ownership and SELinux contexts

Keep the code owned by root and give the apache user only the user/ directory, which holds the configuration and plugins. SELinux is enforcing by default on the RHEL family, so label that directory writable for the web server and allow outgoing connections, which YOURLS uses to fetch the title of each page you shorten.

sudo chown -R root:root /var/www/yourls
sudo chown -R apache:apache /var/www/yourls/user
sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/yourls/user(/.*)?"
sudo restorecon -Rv /var/www/yourls
sudo setsebool -P httpd_can_network_connect on

Create the Apache virtual host

The .htaccess file is only read when overrides are allowed for the directory:

sudo nano /etc/httpd/conf.d/yourls.conf
<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/yourls

    <Directory /var/www/yourls>
        Options FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog /var/log/httpd/yourls_error.log
    CustomLog /var/log/httpd/yourls_access.log combined
</VirtualHost>
sudo apachectl configtest
sudo systemctl restart httpd

Add HTTPS

A shortener that logs you in over plain HTTP exposes your password, so obtain a certificate before the first login. Certbot is available from EPEL:

sudo dnf -y install epel-release
sudo dnf -y install certbot python3-certbot-apache mod_ssl
sudo certbot --apache -d example.com

If you prefer to test over HTTP first, set YOURLS_SITE to the http:// address and change it when the certificate is in place.

Run the installer and verify

Open https://example.com/admin/ in a browser and click the install button; YOURLS creates its tables and reports each one. Then log in with the user name and password from config.php, paste a long URL into the form and open the resulting short URL in a private window to confirm the redirect works.

Back on the server, check that the password has been hashed, then make the configuration read-only, as the YOURLS documentation suggests:

sudo grep -A3 yourls_user_passwords /var/www/yourls/user/config.php
sudo chmod 0440 /var/www/yourls/user/config.php

Troubleshooting and maintenance

  • Short URLs return 404 but the admin area works: the rewrite rules are not applied. Check that .htaccess exists in /var/www/yourls and that the virtual host has AllowOverride All.
  • Database connection errors: re-check the four YOURLS_DB_* values and test them with mariadb -u yourls -p yourls.
  • Permission errors in the log: look for SELinux denials with sudo ausearch -m avc -ts recent.
  • Backups: everything that is yours lives in the database and the user/ directory. Dump the database with mariadb-dump yourls and copy user/ before every upgrade.
  • Upgrades: read the release notes, replace the application files with the new release while keeping user/, then open the admin area, which offers to upgrade the database when needed.

Configuration options and the API are described in the YOURLS documentation.

Frequently asked questions

Can YOURLS run under Nginx instead of Apache?

The stated requirement is Apache with mod_rewrite, but the documentation also publishes a basic Nginx server block whose core is try_files $uri $uri/ /yourls-loader.php$is_args$args;. Use it if you are comfortable adapting Nginx configuration yourself.

Can other people create short links on my installation?

Not while YOURLS_PRIVATE is true: the admin area and the API then require a login. You can add more accounts to $yourls_user_passwords, and the optional YOURLS_PRIVATE_INFOS and YOURLS_PRIVATE_API settings can open the statistics pages or the API separately.

Can I install YOURLS next to an existing website on the same domain?

Yes, in a subdirectory such as example.com/go/; set RewriteBase /go/ and the loader path accordingly. It cannot share one directory with another application that depends on its own .htaccess rewrite rules, such as WordPress.

Should keywords be lowercase or mixed case?

YOURLS_URL_CONVERT decides: 36 generates lowercase keywords and 62 mixed-case ones. Choose before you create links, because changing it later affects how existing keywords are interpreted.

Share story:

Continue reading other guides on How VPS.