---
title: "Deploy YOURLS | (Just Updated) Self-Hosted URL Shortener, Bit.ly Alternative With REST API, Admin Login Generated"
description: "YOURLS URL shortener with click stats and REST API, MariaDB included"
category: "Other"
url: https://railway.com/deploy/yourls-or-just-updated-self-hosted-url-s
---

# 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

**[Deploy YOURLS | (Just Updated) Self-Hosted URL Shortener, Bit.ly Alternative With REST API, Admin Login Generated on Railway](https://railway.com/template/yourls-or-just-updated-self-hosted-url-s)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/yourls-or-just-updated-self-hosted-url-s/manifest.json

- **Creator:** SuperSlowSloth
- **Category:** Other

## Template content

### mariadb

- **Image:** mariadb:11.8@sha256:6422478cb8e159f080fb1d8ccf65101e26fe51385787fde7d16c3b165a331f15
- **Start command:** `/bin/sh -c 'set -e; M=$(cat /sys/fs/cgroup/memory.max 2>/dev/null || echo max); if [ "$M" != max ]; then B=$((M / 2 / 1048576)); [ "$B" -lt 128 ] && B=128; else B=512; fi; export MARIADB_DATABASE=yourls MARIADB_USER=yourls; echo "[railway] uid=$(id -u) innodbBufferPoolMB=$B owner=$(stat -c %u:%g /var/lib/mysql)"; exec docker-entrypoint.sh mariadbd --datadir=/var/lib/mysql/data --innodb-buffer-pool-size=${B}M --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci'`

### yourls

- **Image:** ghcr.io/bon5co/yourls-railway:1.10.6@sha256:48b7a95ef9f7ca204d06f1dcf42b122113c519cb17174d0c843dfc5545868b94
- **Health check:** /healthz
- **Public domain:** Yes

## Documentation

# 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 the `yourls` service)
- Private URL: `http://yourls.railway.internal:8080`
- Credentials: the variable `YOURLS_PASS` on the `yourls` service is the admin password, given as plain text; the login name is `admin` (add a `YOURLS_USER` variable to change it)
- Auth: send `username` and `password` as form fields on every call to `POST /yourls-api.php` (`action=shorturl`, `action=stats`, `action=expand`, `action=url-stats`), with `format=json`. Without them the API answers 403. There is no account registration.
- Health: `GET /healthz` returns 200 without credentials

```bash
#!/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`):

```text
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 `PORT` and 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

- [YOURLS repository](https://github.com/YOURLS/YOURLS)
- [YOURLS documentation](https://yourls.org/docs)
- [Wrapper image source](https://github.com/bon5co/yourls-railway)


## 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) — Self-hosted virtual tabletop for role-playing games (license required)
- [Double Commander in your browser](https://railway.com/deploy/double-commander-in-your-browser) — The Double Commander file manager in the cloud, from any device

Open this page in a browser: https://railway.com/deploy/yourls-or-just-updated-self-hosted-url-s
