Deploying a Self-Hosted Link Shortener With Shlink

Public shorteners are a black box: they own your redirects, log your clicks, and can expire your links on a whim. A self-hosted shortener like Shlink gives you full ownership of every short URL, full visit analytics, and an API you can script. Because the redirects are yours, a link you share today stays yours forever.

This matters more than it sounds. Marketing links, printed QR codes, and product links have long lives, and a middleman can change or retire them at any time. Owning the shortener means the redirects are part of your infrastructure, subject only to your decisions about renewal and retention.

Shlink is a PHP application that pairs with any relational database and exposes a clean REST API plus a modern web UI. This guide sets it up with Docker Compose and shows how to create and track links programmatically.

How Shlink Works

The flow is straightforward: you shorten a long URL, get a short code, and Shlink 302-redirects visitors while recording referrers, user agents, and timestamps. The short codes also power QR codes, custom slugs, and expiry rules, so the same infrastructure handles print and digital campaigns.

For a small business the practical win is attribution you can trust. A short link per campaign tells you exactly which channel drove clicks, and because the data stays in your own database you can run retention or conversion analysis without exporting anything to a third party. Custom slugs keep shared links readable in chat, and a short-lived link can expire automatically for sensitive or time-boxed promotions.

The redirect is a plain 302 by default, which is correct for most tracking use. If you ever need permanent redirects that search engines respect when a link is renamed, Shlink supports the HTTP status per link as well.

Compose Setup

Shlink needs an app container and a database. The official images handle migrations on boot, so the first startup prepares the schema for you:

services:
  shlink:
    image: shlinkio/shlink:4.3
    container_name: shlink
    environment:
      - DEFAULT_DOMAIN=go.example.com
      - DB_DRIVER=mysql
      - DB_HOST=db
      - DB_NAME=shlink
      - DB_USER=shlink
      - DB_PASSWORD=secret-db-pass
    volumes:
      - ./data:/data
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: mariadb:11
    environment:
      - MARIADB_ROOT_PASSWORD=root-secret
      - MARIADB_DATABASE=shlink
      - MARIADB_USER=shlink
      - MARIADB_PASSWORD=secret-db-pass
    volumes:
      - ./db:/var/lib/mysql
    restart: unless-stopped

Set DEFAULT_DOMAIN to the public hostname your short links use. To make short links resolve without a path, add a redirect rule at the domain root in your reverse proxy.

A key operational detail is that Shlink needs a dedicated subdomain, not just any path on an existing site. Routing go.example.com to the container while other hostnames keep pointing at different apps keeps the redirect traffic and its analytics separate. Because the short domain is the face of every link you share, pick something short and memorable at the start — changing it later means every printed link breaks.

Creating Links via the CLI

Shlink ships a handy command-line tool inside the container. Creating a short link is one command:

docker exec shlink shlink short-url:create   --long-url "https://example.com/some/very/long/path"   --tags campaigns,launch   --custom-slug launch

You can also force a custom slug so the result reads cleanly, e.g. go.example.com/launch. Listing visits and exporting stats works the same way:

docker exec shlink shlink visit:list --short-code launch --page 1

Automating With the REST API

Every UI action maps to the REST API. An API key lets you integrate short-links into CI or marketing tooling:

APIKEY=YOUR_API_KEY
curl -X POST https://go.example.com/rest/v3/short-urls   -H "X-Api-Key: $APIKEY"   -H "Content-Type: application/json"   -d '{"longUrl":"https://example.com/report.pdf","customSlug":"report"}'

QR codes are available per short code as well, convenient for print materials that should still be trackable offline.

Because the API is versioned and stable, you can build the shortener into your product pipeline. A checkout or a weekly report can generate a short link automatically, tag it, and file the click counts back into your analytics without any manual step. The API key scopes what an integration can do, so you can hand CI a token with limited permissions rather than giving away full admin access.

Takeaway

Shlink makes your short links permanent, trackable, and scriptable, with QR codes and API access out of the box. It is another lightweight service that shares a small VPS gracefully.

Host Shlink alongside your other apps on a 1 GB Ubuntu Netbay instance, deployed in under 60 seconds at netbayhosts.in.