# Shlink

Shlink is an open-source URL shortener written in PHP, packaged here with PostgreSQL so marketers, small businesses and developers can run their own Bitly alternative in one click. It covers custom slugs, tags, expiry dates and visit limits, a QR code for every link, device and language redirect rules, and visit statistics, managed from the official Shlink web client or its REST API.

- Framework: Dockerfile (Docker)
- Category: Apps / Newsletters and links, Dashboards and analytics
- Creates: a server app and a PostgreSQL database on the Shared tier (1 GB)
- Plan: Lite or above
- Price: Free
- Author: Light Cloud
- Page: https://templates.light-cloud.com/apps/marketing/shlink
- Updated: 2026-11-21

## Features

- The official Shlink 5.1.8 image (PHP on RoadRunner), pinned to an exact release, with migrations run on every start
- Short URLs with custom or generated slugs, titles and tags, and several domains on one install
- A QR code for every link, plus start dates, expiry dates and maximum visit counts
- Redirect rules by device, language or query string, and fallbacks for unknown slugs and the bare domain
- Visit statistics per link, tag and domain: referrer, browser, operating system, and country and city with a free MaxMind key
- A REST API with role-based API keys, the first one created from a generated INITIAL_API_KEY
- Four web workers and one job worker, so the container stays within 512 MiB whatever the host reports

## What you need

- A paid plan: deploying creates a PostgreSQL database, which the Free plan does not include
- DEFAULT_DOMAIN, typed at deploy: the domain your short links use, without https://; without it new links are written as https:/slug
- To run it locally: Docker, for the image and a PostgreSQL container
- The Shlink web client at app.shlink.io, or your own copy of it, to manage links: the server has no screens
- Optional: GEOLITE_LICENSE_KEY, a free MaxMind key; without it visits have no country or city

## About

This is upstream Shlink 5.1.8 by Alejandro Celaya and contributors, under its own MIT licence and unchanged: Light Cloud packages the official image for a one-click deploy, nothing more. lightcloud/start.sh splits DATABASE_URL into Shlink's DB_* settings with TLS on and hands over to upstream's entrypoint, which runs the migrations and creates the first API key, and the Dockerfile fixes the PHP workers at four web and one job worker because upstream's one per CPU used 465 MiB in testing. DEFAULT_DOMAIN has to be typed at deploy, since the platform cannot fill in the app's hostname: use your custom short domain, or the app's Light Cloud address until you add one, and redeploy after changing it. Shlink has no screens of its own, so links are managed from the official web client at app.shlink.io with your app's URL and the generated INITIAL_API_KEY. Visitor locations need GEOLITE_LICENSE_KEY, and the GeoLite database is downloaded again after every restart because the disk is not kept; live updates in the web client need Mercure, RabbitMQ or Redis, which Light Cloud does not offer; and with scale-to-zero the first click after a quiet spell waits a few seconds unless the app keeps a minimum of one instance.

## Variables

- `INITIAL_API_KEY`: generated. Sign in to app.shlink.io with this API key.
- `DEFAULT_DOMAIN`: required. The domain your short links use, such as go.example.com.

## Questions

### What is the best self-hosted alternative to Bitly?

Shlink is one of the most complete: custom domains and slugs, QR codes, tags, expiring links, device-specific redirects and visit statistics, behind a REST API, and free under the MIT licence. YOURLS and Kutt are the other common choices.

### How do I use my own domain for short links?

Point the domain at your Shlink server (on Light Cloud, add it as a custom domain), then set DEFAULT_DOMAIN to it. Shlink can serve several domains at once and lets you choose one per link.

### Does Shlink have a web interface?

The server has none, by design. The official Shlink web client at app.shlink.io runs in your browser and connects with your server's URL and an API key; it is open source and can also be self-hosted as a static site.

### How do I get a QR code for a short link?

Add /qr-code to the short URL, for example https://go.example.com/menu/qr-code. It takes size, format and colour options as query parameters, and the web client shows it next to each link.

### Can Shlink show where visitors come from?

Yes: referrer, browser and operating system for every visit, and country and city once you set a free MaxMind GeoLite2 licence key in GEOLITE_LICENSE_KEY.
