--- title: "Deploy YOURLS" description: "Open-source URL shortener with click stats and its own API" category: "Other" url: https://railway.com/deploy/deploy-yourls --- # Deploy YOURLS Open-source URL shortener with click stats and its own API **[Deploy YOURLS on Railway](https://railway.com/template/deploy-yourls)** Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deploy-yourls/manifest.json - **Creator:** A3A - **Category:** Other - **Total deploys:** 1 ## Template content ### MySQL https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/mysql.svg - **Image:** mysql:9.4 - **Start command:** `docker-entrypoint.sh mysqld --innodb-use-native-aio=0 --disable-log-bin --performance_schema=0 --innodb-buffer-pool-size=1G` ### YOURLS https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/yourls.svg - **Source:** https://github.com/gridalpha/yourls-railway - **Health check:** /admin/ - **Public domain:** Yes ## Documentation # 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. ![Diagram of the YOURLS and MySQL services on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1788897217/yourls-architecture.png) ## 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. ![YOURLS admin listing five short links and their click counts](https://res.cloudinary.com/rroe4rtk/image/upload/v1788897220/yourls-admin-dashboard.png) ![Traffic statistics chart for a single YOURLS short link](https://res.cloudinary.com/rroe4rtk/image/upload/v1788897221/yourls-link-stats.png) ![YOURLS plugin manager listing the six bundled plugins](https://res.cloudinary.com/rroe4rtk/image/upload/v1788897222/yourls-plugins.png) ## 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](https://github.com/gridalpha/yourls-railway), one layer on the official [`yourls:apache`](https://hub.docker.com/_/yourls) 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 | Variable | Purpose | |---|---| | `YOURLS_SITE` | Public base URL of your shortener, no trailing slash | | `YOURLS_USER` | Admin username | | `YOURLS_PASS` | Admin password | | `YOURLS_COOKIEKEY` | Signs the session cookie; changing it logs everyone out | | `YOURLS_PRIVATE` | `true` (default) restricts link creation and stats to your account | | `YOURLS_DB_HOST` | `host:port` of the MySQL service | | `YOURLS_DB_USER` | Scoped database role, created on first boot | | `YOURLS_URL_CONVERT` | `36` for lowercase keywords, `62` for mixed case | | `YOURLS_UNIQUE_URLS` | `false` allows several short links to one target | | `YOURLS_NOSTATS` | `true` turns off click logging | ### Deployment Dependencies - Source repository: - Upstream project: (MIT licensed) - Official image: - Configuration reference: ## Hardware Requirements for Self-Hosting YOURLS | Resource | Minimum | Recommended | |---|---|---| | CPU | 0.5 vCPU | 1 vCPU | | RAM | 512 MB total | 1 GB total | | Storage | 1 GB volume + database | 5 GB volume + database | | Runtime | PHP 8.1+, MySQL 5.7+ / MariaDB 10.3+ | PHP 8.5, MySQL 9 | 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. ## Similar templates - [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀 - [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform - [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy. Open this page in a browser: https://railway.com/deploy/deploy-yourls