shlink-docker-compose/README.md

Shlink Docker Compose

Self-hosted Shlink URL shortener with the official web dashboard, backed by PostgreSQL. Intended to run behind a reverse proxy that terminates TLS.

Stack

Service	Image	Container port	Default host port
shlink	shlinkio/shlink:stable	8080	8500
shlink-dashboard	shlinkio/shlink-web-client:stable	8080	8501
shlink-db	postgres:16-alpine	5432	not exposed

Quick start

cp .env.example .env
# Edit .env — set DEFAULT_DOMAIN, SHLINK_PUBLIC_URL, INITIAL_API_KEY, POSTGRES_PASSWORD
docker compose up -d

Generate strong secrets:

openssl rand -hex 32   # INITIAL_API_KEY
openssl rand -hex 24   # POSTGRES_PASSWORD

Environment variables

Variable	Required	Description
DEFAULT_DOMAIN	yes	Bare host used to build short URLs (e.g. s.example.com). No scheme.
SHLINK_PUBLIC_URL	yes	Full public URL of the Shlink API (e.g. https://s.example.com). Used by the dashboard.
INITIAL_API_KEY	yes	API key created on first boot. Also preconfigures the dashboard.
POSTGRES_PASSWORD	yes	PostgreSQL password.
IS_HTTPS_ENABLED	no	true (default) if your reverse proxy terminates TLS. Set false for plain HTTP.
GEOLITE_LICENSE_KEY	no	MaxMind GeoLite2 license key for IP geolocation.
TIMEZONE	no	Defaults to UTC.
POSTGRES_DB	no	Defaults to shlink.
POSTGRES_USER	no	Defaults to shlink.
SHLINK_SERVER_PORT	no	Host port for the Shlink API. Defaults to 8500.
SHLINK_DASHBOARD_PORT	no	Host port for the dashboard. Defaults to 8501.

Reverse proxy

Two hostnames recommended:

• s.example.com → http://127.0.0.1:8500 — Shlink API and short URL redirects.
• shlink-admin.example.com → http://127.0.0.1:8501 — Dashboard UI.

The proxy must terminate TLS and forward X-Forwarded-Proto / X-Forwarded-For so Shlink renders https:// short URLs and logs the correct client IP.

DEFAULT_DOMAIN must match the hostname your proxy serves the API on, otherwise generated short URLs will be wrong.

Persistence

Two named volumes:

• shlink-data — Shlink cache and runtime files.
• shlink-db-data — PostgreSQL data directory.

Back both up before upgrades.

Common operations

docker compose logs -f shlink            # follow server logs
docker compose exec shlink shlink --help # CLI inside the container
docker compose pull && docker compose up -d   # upgrade images
docker compose down                      # stop (data preserved)

Create an additional API key:

docker compose exec shlink shlink api-key:generate

Notes

• INITIAL_API_KEY only takes effect on the very first boot, before the database is initialized. Changing it later does nothing — use api-key:generate instead.
• The dashboard ships preconfigured with one server pointed at SHLINK_PUBLIC_URL. The browser must be able to reach that URL; it is not a server-to-server call.
• Postgres is intentionally not exposed on the host. Connect via docker compose exec shlink-db psql -U shlink.