
Deploy YOURLS | (Just Updated) Self-Hosted URL Shortener, Bit.ly Alternative With REST API, Admin Login Generated
YOURLS URL shortener with click stats and REST API, MariaDB included
mariadb
Just deployed
/var/lib/mysql
Just deployed
Deploy and Host YOURLS on Railway
Built for an LLM agent to deploy and use. The deploy form has no fields to fill: the admin password, the cookie key and the database password are generated, the server cannot start without a strong login, and the database tables are created at boot. YOURLS (Your Own URL Shortener) is a self-hosted URL shortener with a web admin, click statistics, custom keywords, bookmarklets and a REST API, an open-source alternative to Bitly and TinyURL on your own domain.
About Hosting YOURLS
This template runs two services: yourls, the upstream YOURLS image, pinned by digest, through a thin wrapper, and mariadb, a MariaDB 11.8 database with a volume at /var/lib/mysql. All YOURLS data (links, click logs, options) lives in MariaDB, so the application service needs no volume. One public domain serves the redirects at /KEYWORD, the admin at /admin and the API at /yourls-api.php. The server listens on Railway's injected PORT, and the healthcheck is GET /healthz.
What the wrapper fixes. Upstream's Apache listens on a fixed 8080 instead of Railway's injected PORT, takes its admin login from YOURLS_USER and YOURLS_PASS with no minimum length, falls back to a random cookie key at every start (so every redeploy signs everyone out), and leaves the database tables for a human to create on /admin/install.php, which any visitor can do first. The wrapper refuses to start without a login password of at least 12 characters and a fixed cookie key, listens on PORT, creates the tables at boot and serves /healthz. Railway also brings back an Apache MPM that upstream removed in a later layer and Apache then refuses to start with AH00534: More than one MPM loaded; the wrapper disables it at boot. This was measured on a Railway deploy of the first wrapper build, whose deployment failed its healthcheck with that error until the fix. Not reproduced on a Railway control of the incumbent listing.
Using it. Open the domain, go to /admin and sign in as admin with YOURLS_PASS. Create short links in the admin, or through the API with the same login. The login name is admin unless you add a YOURLS_USER variable. Redeploys keep the same login, the same cookie key and every link, because the data is in MariaDB on its volume.
Agent contract
- Public URL:
https://RAILWAY_PUBLIC_DOMAIN(the generated domain of theyourlsservice) - Private URL:
http://yourls.railway.internal:8080 - Credentials: the variable
YOURLS_PASSon theyourlsservice is the admin password, given as plain text; the login name isadmin(add aYOURLS_USERvariable to change it) - Auth: send
usernameandpasswordas form fields on every call toPOST /yourls-api.php(action=shorturl,action=stats,action=expand,action=url-stats), withformat=json. Without them the API answers 403. There is no account registration. - Health:
GET /healthzreturns 200 without credentials
#!/bin/sh
# needs: RAILWAY_PUBLIC_DOMAIN, YOURLS_PASS (variable of the yourls service; the login name is admin unless you add a YOURLS_USER variable); also curl, sed.
R="https://$RAILWAY_PUBLIC_DOMAIN"
API="$R/yourls-api.php"
LOGIN="${YOURLS_USER:-admin}"
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/healthz")" = 200 ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/healthz"
# signup: none - YOURLS has one admin login set by YOURLS_USER and YOURLS_PASS and no account registration
U="https://example.com/railway-probe-$(date +%s)"
# a stranger cannot read statistics or create a short link: no credentials and a wrong password are both refused
curl -s -G --data-urlencode "action=stats" --data-urlencode "format=json" "$API" -o /dev/null -w "read without key: %{http_code}\n"
curl -s -X POST --data-urlencode "action=shorturl" --data-urlencode "format=json" --data-urlencode "url=$U" "$API" -o /dev/null -w "write without key: %{http_code}\n"
curl -s -X POST --data-urlencode "action=shorturl" --data-urlencode "format=json" --data-urlencode "url=$U" --data-urlencode "username=$LOGIN" --data-urlencode "password=not-the-admin-login" "$API" -o /dev/null -w "write with wrong key: %{http_code}\n"
# the generated login creates a short link, the link redirects, and the statistics read back
SHORT=$(curl -s -X POST --data-urlencode "action=shorturl" --data-urlencode "format=json" --data-urlencode "url=$U" --data-urlencode "username=$LOGIN" --data-urlencode "password=$YOURLS_PASS" "$API" | sed -n 's/.*"shorturl": *"\([^"]*\)".*/\1/p' | sed 's#\\##g')
if [ -n "$SHORT" ]; then echo "write with key: ok"; else echo "write with key: FAILED"; fi
curl -s -o /dev/null -w "redirect: %{http_code}\n" "$R/${SHORT##*/}"
curl -s -X POST --data-urlencode "action=stats" --data-urlencode "format=json" --data-urlencode "username=$LOGIN" --data-urlencode "password=$YOURLS_PASS" "$API" -o /dev/null -w "read with key: %{http_code}\n"
Expected output against a fresh deploy (measured on the Railway demo and on a control deploy of the published code; the output is recorded in template.md):
health: 200
read without key: 403
write without key: 403
write with wrong key: 403
write with key: ok
redirect: 301
read with key: 200
The refusals are the contract: write without key: 403, write with wrong key: 403 and read without key: 403 on the API. There is no sign-up route, which the # signup: none line in the snippet states.
Why Deploy YOURLS on Railway?
Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.
By deploying YOURLS on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.
- Agent-ready - no deployer fields, a contract block, and one script that proves the server is healthy, a stranger cannot create or read links, and the generated login creates a link that redirects.
- Locked from the first request - the server will not start without a strong admin password, and the tables exist before the first visit, so nobody can claim the install page.
- Works on first deploy - the listener follows Railway's injected
PORTand Apache starts with a single MPM. - Data survives redeploys - links and click logs live in MariaDB on a volume, and the cookie key is fixed so sessions survive.
- Pinned - the upstream image is pinned by digest and the wrapper by tag and digest.
Common Use Cases
- Branded short links on your own domain - replace Bitly or TinyURL links with your own, with keywords you choose.
- Link tracking for campaigns - per-link click counts, referrers and countries in the admin.
- Short links created by scripts and agents - one authenticated API call returns a short URL.
Dependencies for YOURLS Hosting
- The yourls service and a MariaDB service with its volume, both created by the template.
Deployment Dependencies
Template Content
mariadb
mariadb:11.8