YOURLS URL Shortener on AWS User Guide

Overview

YOURLS (Your Own URL Shortener) is a popular self-hosted open source link shortener. It lets you create short links on your own domain, choose custom keywords, and keep the click analytics - hits over time, referrer sources and country breakdowns - on infrastructure you control rather than a third-party service, with a bookmarklet and a full REST API included. This cloudimg image delivers YOURLS fully installed and security hardened: Apache with PHP 8.3 fronts the application, MariaDB holds every short link and click, the installer is pre-completed at build time so no open setup wizard ships, and short-URL routing is configured in the web server (not in an .htaccess a default configuration ignores) so links resolve the moment you launch. A unique MariaDB password, a unique YOURLS administrator password, and a fresh authentication cookie key are generated on the first boot of every instance and written to a root-only file, so no shared or default credential ships in the image. All of your data - the MariaDB database plus the YOURLS configuration and any plugins you add - lives on a dedicated data volume kept separate from the operating system disk. Backed by 24/7 cloudimg support.

What is included:

• YOURLS 1.10.4 served by Apache on port 80 with PHP 8.3 and OPcache
• MariaDB holding the links and click analytics, bound to the loopback interface only
• The installer pre-completed and short-URL routing configured in the Apache virtual host, so no open setup step is reachable
• Unique MariaDB and administrator passwords, plus a fresh cookie key, generated on first boot and recorded in a root-only file
• The administrator password stored only as a bcrypt hash; the application follows whatever address you browse it on, so it works on the instance address and after you attach your own domain with no edit
• A dedicated data volume carrying the MariaDB datadir and the YOURLS user/ tree
• apache2.service and mariadb.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An AWS account, an EC2 key pair in the target region, and a VPC with a public subnet. m5.large (2 vCPU / 8 GiB RAM) is the recommended instance type. Security group inbound: allow 22/tcp from your management network for SSH and 80/tcp (and 443/tcp once you enable HTTPS) for the web interface.

Step 1 - Launch the AMI

Subscribe to the listing in AWS Marketplace, choose Continue to Launch, and launch through the EC2 console or the AWS CLI. Select the m5.large instance type, your key pair, and a security group that opens ports 22 and 80.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <security-group-id> \
  --subnet-id <subnet-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=yourls}]'

Step 2 - Connect to your instance

Connect over SSH as the default login user for the OS variant you launched. This listing may ship more than one OS variant; use the matching login user below.

Step 3 - Confirm the services are running

YOURLS is served by Apache and PHP, backed by MariaDB, with a one-shot first-boot service that mints the per-instance credentials. Confirm the two long-running services are healthy:

systemctl is-active apache2.service mariadb.service

Each reports active:

active
active

Step 4 - Verify the stack and endpoints

Confirm the deployed YOURLS version, that MariaDB is bound to the loopback interface only, that the health endpoint answers, that the admin interface is up, and that the site root redirects to it (YOURLS ships no public front page by default):

grep -oE "YOURLS_VERSION', '[0-9.]+'" /var/www/yourls/includes/version.php
php -v | head -1
ss -tln | grep 127.0.0.1:3306
curl -s -o /dev/null -w 'healthz: HTTP %{http_code}\n' http://127.0.0.1/healthz
curl -s -o /dev/null -w 'admin:   HTTP %{http_code}\n'  http://127.0.0.1/admin/
curl -s -o /dev/null -w 'root:    HTTP %{http_code}\n'  http://127.0.0.1/

Expected output (the site root answers 302, redirecting to /admin/):

YOURLS_VERSION', '1.10.4'
PHP 8.3.6 (cli) (built: Jul 16 2026 18:30:41) (NTS)
LISTEN 0      80         127.0.0.1:3306      0.0.0.0:*
healthz: HTTP 200
admin:   HTTP 200
root:    HTTP 302

The database and the YOURLS user/ tree both live on the dedicated data volume, separate from the OS disk:

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

/dev/nvme1n1 /data
/dev/nvme1n1[/mysql] /var/lib/mysql
/dev/nvme1n1[/yourls/user] /var/www/yourls/user

Step 5 - Read your first-boot credentials

On the first boot of every instance, a one-shot service generates a unique administrator password and a unique database password and records them, along with the browse address, in a root-only file. Read them:

sudo cat /root/yourls-credentials.txt

The administrator username is admin and the password is the value of YOURLS_ADMIN_PASSWORD. The administrator password exists in plaintext only in this root-only file - in the YOURLS configuration it is stored solely as a bcrypt hash. Once you have saved it in your own password manager you may delete this file.

Step 6 - Prove the sign-in round-trip

Confirm the recorded administrator password authenticates end-to-end against the live login form, and that the session cookie comes back host-only (the correct, browser-accepted scope for a single-host appliance):

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

ROUNDTRIP OK: admin authenticated against the live login form; session cookie is host-only

Step 7 - Sign in to the admin interface

Browse to http://<instance-public-ip>/ in your browser (it redirects to the admin interface) and sign in with the username admin and the password from Step 5.

Step 8 - Shorten a link

In the admin interface, paste a long URL into Enter the URL, optionally set a custom keyword, and choose Shorten The URL. YOURLS returns the short link and a stats link for it. Short links resolve at http://<instance-public-ip>/<keyword>.

Every short link you create is listed with its original URL, creation date, source IP and live click count:

Step 9 - Review click analytics

Open a link's statistics page (the + after a short URL) to see its click history over time, historical counts, and the traffic-location and traffic-source breakdowns powered by the bundled GeoLite2 database:

Step 10 - Attach your own domain and enable HTTPS

YOURLS derives its site address from the request Host header, so it works on the instance IP immediately and keeps working the moment you point a domain at the instance - there is no configuration file to edit. To serve the shortener under your own domain over HTTPS, point an A record at the instance, then install a certificate with Certbot:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-apache
sudo certbot --apache -d links.your-domain.example

Open 443/tcp in the security group. The host-only authentication cookie and the short-URL routing continue to work unchanged under the new domain and under HTTPS.

How the image is secured

• No shared credential ships. YOURLS has no user table - the single administrator entry in the configuration is the complete account list. Its password, the database grant and the authentication cookie key are all rotated to discarded random values at build time and re-minted per instance on first boot, so the shipped image authenticates nothing until your instance boots.
• The database is loopback-only. MariaDB listens on 127.0.0.1 and the security group never opens 3306.
• The configuration and library files are not web-reachable. The file holding the database password and administrator hash, and the internal PHP/library tree (including the 9 MB GeoLite2 database), return 403 over HTTP, while the browser assets the admin interface needs still serve normally.
• First boot is a one-shot. yourls-firstboot.service runs once, rotates every secret, records the browse address, and then does not run again on later reboots - that is expected and not a fault.

Support

cloudimg provides 24/7 technical support for this YOURLS image by email (support@cloudimg.co.uk) and live chat: deployment and configuration, custom domain and TLS setup, plugin and REST API configuration, version upgrades, performance tuning, and MariaDB database administration. For billing or subscription changes, contact support@cloudimg.co.uk.