YOURLS URL Shortener on Ubuntu 24.04 on Azure User Guide

Overview

YOURLS (Your Own URL Shortener) is an established open source link shortener you run yourself. It turns long URLs into short ones under your own domain, letting you either auto generate a keyword or choose your own, and it tracks every click: hits over time, the referrer sources sending traffic, and a country breakdown. Beyond the admin interface it offers a bookmarklet, a full REST API for creating and querying links from your own code, and a plugin system. The cloudimg image ships YOURLS 1.10.4 served by Apache and PHP 8.3 on a hardened, fully patched Ubuntu 24.04 LTS base, together with a bundled local MariaDB server so the appliance is complete and useful on its own. The installer is already completed and short link routing is configured in the web server itself, so links resolve the moment the instance boots. The bundled MariaDB listens only on the loopback interface (127.0.0.1:3306) and keeps its data on a dedicated Azure data disk. A unique administrator password is generated on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• YOURLS 1.10.4 served by Apache with PHP 8.3, managed by systemd
• A bundled MariaDB server holding the YOURLS database, already installed and ready
• The installer pre completed, so no setup wizard is ever exposed
• Short link routing configured in the Apache virtual host, so links resolve correctly from the first boot
• A per VM administrator password generated on first boot and recorded in a root only file
• No shipped default login: the administrator password ships rotated to a discarded random and the real per VM password is set on first boot
• The administrator password stored only as a bcrypt hash, never in clear text
• MariaDB bound to 127.0.0.1 only, never exposed to the network
• A dedicated Azure data disk carrying both the MariaDB database and the YOURLS user tree
• Each instance follows whatever address you browse it on, so it works on the instance address and keeps working after you attach your own domain
• Host only session cookies, so sign in works whether you browse by IP or by a DNS name
• An empty shortener: the upstream sample links are removed, so your first link is your own
• apache2.service and mariadb.service as enabled systemd units
• An unauthenticated /healthz endpoint for Azure Load Balancer health probes
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a sensible starting point for a shortener serving a team or a modest public audience; move up to Standard_D2s_v3 for high redirect volumes or large click histories. NSG inbound: allow 22/tcp from your management network, 80/tcp for the application and 443/tcp if you terminate TLS on the VM. The bundled MariaDB is never exposed: it listens on 127.0.0.1 only, so port 3306 stays off the network.

Step 1 - Deploy from the Azure Marketplace

In the Azure portal choose Create a resource, search for YOURLS URL Shortener on Ubuntu 24.04 LTS by cloudimg, and select Create. Pick your subscription, resource group and region, choose the Standard_B2s size, select SSH public key authentication with the username azureuser, and allow inbound 22, 80 and 443. The image attaches its own 20 GiB data disk for your links and click analytics, so you do not need to add one.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name yourls \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Then open ports 80 and 443:

az vm open-port --resource-group <your-rg> --name yourls --port 80,443

Step 3 - Confirm the services are running

SSH to the VM as azureuser and confirm Apache and MariaDB are active. Note that MariaDB is bound to 127.0.0.1:3306 only, while Apache serves on port 80.

systemctl is-active apache2 mariadb

ss -tlnH | grep -E ':80 |:3306 ' | sed 's/  */ /g'

Confirm that the first boot credential rotation completed. It leaves a marker file behind, which is the check that stays true for the life of the VM:

test -f /var/lib/cloudimg/yourls-firstboot.done && echo "first boot: completed"

yourls-firstboot is a one shot service: it runs once, on the very first boot of your VM, to generate this instance's credentials, and then disables itself so it can never run again and overwrite them. That means systemctl is-enabled yourls-firstboot reports disabled and, after any reboot, systemctl is-active yourls-firstboot reports inactive. Both are the expected, healthy states for a service that has already done its job, which is why the marker file above rather than the service state is the thing to check.

Step 4 - Retrieve the per VM administrator password

The first boot service generates an administrator password unique to your VM and writes it to a root only file. Read it over SSH:

sudo cat /root/yourls-credentials.txt

YOURLS_URL is the address the VM resolved for itself on first boot: the public IP when the VM has one, otherwise its private address. It is recorded for reference and for command line tooling on the VM. YOURLS itself follows whatever address you actually browse it on, so you do not need to edit any configuration when you attach a DNS name or when a stop and start changes the public IP.

Step 5 - Sign in

Browse to http://<vm-ip>/admin/ and sign in with the username admin and the password from the credentials file. Browsing to http://<vm-ip>/ redirects here.

After signing in you land on the admin interface, which shows your link total and click total, the box for shortening a new URL, and the table of every link you have created. A fresh instance is empty, as shown below: the upstream sample links are removed during the build, so the first link in the table will be your own.

Step 6 - Shorten your first link

Paste a long URL into Enter the URL. Leave Custom short URL blank to have YOURLS generate a keyword for you, or type one to choose your own, then select Shorten The URL. The new link appears immediately with its short URL, the original URL, the date, and a click counter.

The short URL is built from the address you are browsing, so the link you are handed is one your audience can actually use. Visiting it redirects straight to the original URL and records a click.

Step 7 - Read the click analytics

Every link has a statistics page. Append a + to any short URL, or select the Stats link, to open it. YOURLS reports the historical click count over the last 24 hours, 7 days, 30 days and all time, your best day, plus tabs for traffic location and traffic sources.

The country breakdown under Traffic location is resolved on the VM itself from a GeoLite2 database bundled with YOURLS, so your visitors' addresses are never sent to a third party service.

Step 8 - No known or default credentials

This image ships with no usable login. The administrator password baked at build time is rotated to a random value that is discarded and never recorded, and the first boot service sets a fresh password unique to your VM before YOURLS serves a single request.

YOURLS has no user table: its accounts live entirely in one array in its configuration file, so the single admin entry below is the complete list of accounts on this instance. It is stored as a bcrypt hash, never in clear text. The round trip check confirms that the per VM password authenticates against the real sign in form and that the session cookie is issued host only.

sudo grep -A2 'yourls_user_passwords' /var/www/yourls/user/config.php | grep phpass | cut -c1-46

sudo bash /usr/local/sbin/yourls-cred-roundtrip.sh

To change the administrator password to one of your own, edit the $yourls_user_passwords array in /var/www/yourls/user/config.php. You can put your new password there in plain text and YOURLS will replace it with a hash the first time you sign in, but that requires making the file writable by the web server. The safer option, and the one this image is built around, is to write the hash yourself and leave the file read only:

sudo php -r 'echo "phpass:".password_hash("<new-password>", PASSWORD_BCRYPT)."\n";'

Paste the printed value in place of the existing phpass:... string for the admin entry, keeping the surrounding quotes, then reload Apache with sudo systemctl reload apache2.

Step 9 - Verify the stack and where your data lives

Confirm the installed release, the health endpoint and the data disk layout. Both the MariaDB database (every short link and every click) and the YOURLS user tree (your configuration plus any plugins or pages you add) live on the dedicated data disk, bind mounted into place, so your data is kept off the operating system disk.

grep YOURLS_VERSION /var/www/yourls/includes/version.php

curl -sI http://127.0.0.1/healthz | sed -n 1p

findmnt -no SOURCE,TARGET,FSTYPE,SIZE /data; findmnt -no SOURCE,TARGET /var/lib/mysql; findmnt -no SOURCE,TARGET /var/www/yourls/user

Adding your own domain and TLS

A shortener is only as good as the domain in front of it, so this is the step that makes the instance genuinely yours. Point a DNS A record at the VM's public IP, then issue a certificate with Certbot:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-apache
sudo certbot --apache -d s.your-domain.example --agree-tos -m you@your-domain.example --redirect

Certbot configures Apache for HTTPS and installs a renewal timer. There is nothing else to change: YOURLS on this image builds its short links, its pages and its sign in form from the address you browse, so once your domain resolves and TLS is terminated, every new link is issued as https://s.your-domain.example/keyword automatically. Links created before you attached the domain keep their keyword and are served on the new domain too.

Backing up

Everything worth keeping is on the data disk: the MariaDB database and the user tree. For a full machine level backup, take an Azure snapshot of the data disk, or dump the database and archive the tree:

sudo mysqldump --protocol=socket -uroot --single-transaction yourls > /var/tmp/yourls-backup.sql
sudo tar -czf /var/tmp/yourls-user.tar.gz -C /data/yourls user

Store both off the VM. The simplest scheduled option is an Azure Backup policy on the VM plus its data disk.

Security notes

• The YOURLS configuration file, which holds the database password and the administrator hash, is denied at the web server and cannot be fetched over HTTP.
• The bundled MariaDB listens on 127.0.0.1:3306 only. Keep port 3306 closed in your NSG; nothing outside the VM needs it.
• The administrator and database passwords are unique to your VM, generated on first boot, and written only to /root/yourls-credentials.txt with 0600 root:root permissions. The administrator password is stored in the configuration only as a bcrypt hash.
• The YOURLS code tree is owned by root and is not writable by the web server.
• Session cookies are issued host only, so sign in behaves correctly whether you browse the instance by IP or through a DNS name.
• The admin area and the API require your password: YOURLS runs in private mode. Only the short link redirects themselves are public, which is what a shortener is for.
• Serve the shortener over HTTPS before you publish links, and restrict 22/tcp to your management network.
• The base OS is fully patched at build time and unattended security upgrades remain enabled on your VM.

Trademark

YOURLS is a trademark of its respective owner. cloudimg is not affiliated with, endorsed by, or sponsored by the YOURLS project. This image packages the open source YOURLS software, which is distributed under the MIT licence, and all product and company names are the property of their respective holders. YOURLS includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.

Support

cloudimg provides 24/7 technical support for this image by email (support@cloudimg.co.uk) and live chat, covering deployment, configuration, custom domain setup, upgrades, performance tuning and MariaDB administration. Critical issues receive a one hour average response time.