Deploy YOURLS

Deploy and Host YOURLS on Railway

YOURLS — Your Own URL Shortener — is the long-running open-source answer to Bitly. It turns long links into short ones on a domain you control, counts every click, and records where each visitor came from, so the data behind your links stays in your own database rather than a vendor's. It is a small PHP application with a plugin API, a documented HTTP API and a web admin. Self-host YOURLS when you want branded short links that keep working even if a shortening service shuts down, and analytics you can read without a plan upgrade.

Deploy YOURLS on Railway and you get two services. YOURLS runs the application on Apache and PHP 8.5 and is the only service exposed to the internet; MySQL is a Railway-managed database reachable only over the project's private network. On first boot the YOURLS service creates its own database and a MySQL role scoped to that database alone, then creates the yourls_url, yourls_options and yourls_log tables — the setup wizard you would normally click through is already done by the time the URL answers. A volume at /var/www/html/user keeps your configuration, plugins and translations across redeploys.

Getting Started with YOURLS on Railway

Open the deployed URL and you land on the admin login at /admin/. Sign in with the username and password you set as YOURLS_USER and YOURLS_PASS — there is no registration step and no default credential to change, because the admin account is the pair of variables you supplied. The first screen is the link table, holding three example links you can delete. Paste a long URL into Enter the URL, optionally type a keyword such as docs into Custom short URL, and press Shorten The URL to get back https://your-domain/docs.

Open that short link in an incognito window to confirm the redirect, then reload the admin: the Clicks column increments and the IP column shows the real visitor address rather than a proxy, because the template configures Apache to read the forwarded client address. Click the bar-chart icon on any row for per-link statistics — hits by hour and day, referrers and visitor country. Manage Plugins lists the bundled plugins, and Tools holds the bookmarklets and the HTTP API details. To let anyone submit links, set YOURLS_PRIVATE to false; leave the default and every page and API call requires your credentials.

About Hosting YOURLS

A URL shortener looks trivial until you own one: it has to resolve keywords fast, never lose a mapping, and keep a click log you can query later. YOURLS does all of that in a few hundred kilobytes of PHP backed by MySQL, which is why it has outlived most of its competitors. Teams self-host it when short links are part of the brand — a go/ link in internal docs, a campaign link in an email — and have to keep resolving for years.

Key features:

• Custom or generated keywords, lowercase (base 36) or mixed case (base 62)
• Click statistics per link: hourly and daily graphs, historical totals, best day
• Referrer and country breakdowns for every short URL
• An HTTP API with signature-based authentication for scripts and integrations
• A plugin API with action and filter hooks, and a large community plugin ecosystem
• Private mode, on by default, so only your account can create links or read stats

The Railway architecture is two services. YOURLS serves every request — admin, API and the redirects themselves — and holds user content on its volume. MySQL stores the links, options and click log, and has no public domain, so the only route to your data is through the application.

Why Deploy YOURLS on Railway

Railway removes the annoying parts of self-hosting a PHP app:

• HTTPS and a public domain are provisioned for you, custom domains a click away
• MySQL is managed, backed up and reachable only on the private network
• The volume keeps plugins and configuration across every redeploy
• The database and its scoped role are created on first boot — no setup wizard
• Scaling memory or CPU is a slider, not a migration

Common Use Cases

• Branded campaign links. Publish links.yourcompany.com/spring instead of a generic shortener, and keep the click data for attribution.
• Internal go-links. Give every runbook and dashboard a short address that survives the underlying URL changing.
• Print, QR codes and podcasts. Anywhere a URL is read aloud or typed by hand, a keyword you own beats a random string.
• Programmatic shortening. Call /yourls-api.php from a CMS, a newsletter builder or a CI job to mint links automatically.

Dependencies for YOURLS

• YOURLS — built from gridalpha/yourls-railway, one layer on the official yourls:apache image (YOURLS 1.10.6, PHP 8.5, Apache). It runs the installer at boot, provisions a scoped database role, and configures Apache for Railway's port and forwarded client IP.
• MySQL — Railway's managed MySQL 9.4. Every link, option and click is stored here.

Environment Variables Reference

Deployment Dependencies

• Source repository:
• Upstream project: (MIT licensed)
• Official image:
• Configuration reference:

Hardware Requirements for Self-Hosting YOURLS

The redirect path is one indexed lookup and one insert, so a single container handles far more traffic than most shorteners see. Growth shows up in the database first, since the click log gains a row per visit — plan storage around yourls_log, not the application.

Self-Hosting YOURLS with Docker

The official image needs a MySQL server and four variables. The following is a minimal Docker Compose file:

services:
  yourls:
    image: yourls:apache
    ports:
      - "8080:8080"
    environment:
      YOURLS_SITE: https://example.com
      YOURLS_USER: admin
      YOURLS_PASS: change-me
      YOURLS_DB_HOST: mysql
      YOURLS_DB_PASS: example
    depends_on:
      - mysql
  mysql:
    image: mysql:9
    environment:
      MYSQL_ROOT_PASSWORD: example
      MYSQL_DATABASE: yourls

Bring it up, then finish installation at http://localhost:8080/admin/install.php:

docker compose up -d
docker compose logs -f yourls

On Railway that manual step happens at boot, so the first URL you open is already the login screen.

How Much Does YOURLS Cost to Self-Host?

YOURLS is free and MIT licensed. There is no paid edition, no seat count and no link quota — the whole project, plugin API included, is the code in the GitHub repository. The only cost of running it on Railway is infrastructure: the container, the managed MySQL database, and the volume holding your configuration and plugins.

FAQ

What is YOURLS? YOURLS is an open-source URL shortener written in PHP. You run it on your own domain, and it stores every short link and every click in a MySQL database you control, with an admin interface, a plugin API and an HTTP API on top.

What does this Railway template deploy? Two services: YOURLS itself, built from the official image with a boot-time installer added, and a managed MySQL database on the private network. A volume holds configuration and plugins, and a public HTTPS domain is issued for the app.

Why does the template include a MySQL database? YOURLS keeps no state on disk apart from configuration and plugin files. Links, settings and the entire click history live in MySQL, so the database is what you back up and what you migrate to a new deployment.

How do I create short links from a script instead of the admin? Use the API at /yourls-api.php. Requests authenticate with your username and password or with the signature token shown under Tools, and action=shorturl returns the short URL as JSON or XML.

Can I use my own domain for short links? Yes, and you should — a short link is only short if the domain is. Add a custom domain to the YOURLS service in Railway, then set YOURLS_SITE to https://your-domain so generated links and the admin agree on the hostname.