Skip to content
Klutch.sh Docs

Deploying a Shlink App

Introduction

Shlink is an open-source URL shortener with REST APIs, QR codes, and rich analytics. Deploying Shlink with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage—all configured from klutch.sh/app. This guide covers installation, Dockerfile setup, environment variables, storage, Nixpacks overrides, and sample checks.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Shlink Dockerfile (GitHub is the only supported git source)
  • External database (MySQL/PostgreSQL) for Shlink metadata
  • Domain and TLS for your short links

For onboarding, see the Quick Start.

Architecture and ports

  • Shlink serves HTTP on internal port 8080. Choose HTTP traffic in Klutch.sh and set the internal port to 8080.
  • Persistent storage is optional (for logs or cached data); primary state resides in your external database.

Repository layout

shlink/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Build and run locally (ensure DB is reachable):

Terminal window
docker build -t shlink-local .
docker run -p 8080:8080 \
  -e DB_DRIVER=postgres \
  -e DB_NAME=shlink \
  -e DB_USER=shlink \
  -e DB_PASSWORD=changeme \
  -e DB_HOST=localhost \
  -e DB_PORT=5432 \
  shlink-local

Place this at the repo root; Klutch.sh auto-detects Dockerfiles.

FROM shlinkio/shlink:stable


ENV PORT=8080


EXPOSE 8080
CMD ["shlink", "server:run", "--host=0.0.0.0", "--port=8080"]

Notes:

  • Pin to a specific tag (e.g., shlinkio/shlink:3.10.1) for stability.
  • server:run starts the API/UI on the configured port.

Environment variables (Klutch.sh)

Set these before deploying:

  • PORT=8080
  • Database:
    • DB_DRIVER=postgres (or mysql)
    • DB_NAME=<db-name>
    • DB_USER=<db-user>
    • DB_PASSWORD=<db-password>
    • DB_HOST=<db-host>
    • DB_PORT=<port>
  • App settings:
    • DEFAULT_DOMAIN=example-app.klutch.sh
    • BASE_PATH= (leave empty unless you host under a path)
    • GEOLITE_LICENSE_KEY=<key> (if using MaxMind geolocation)

If deploying without the Dockerfile and relying on Nixpacks:

  • NIXPACKS_PHP_VERSION=8.2 (adjust if needed)
  • NIXPACKS_START_CMD=shlink server:run --host=0.0.0.0 --port=8080

Attach persistent volumes

If you store logs or cache locally, add storage in Klutch.sh (path and size only):

  • /etc/shlink — config/cache/logs.

Ensure the path is writable inside the container.

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add the environment variables above (DB credentials, domain, optional MaxMind key).
  5. Attach a volume at /etc/shlink if you want local config/cache persistence.
  6. Deploy. Your shortener will be reachable at https://example-app.klutch.sh.

Sample checks

Health:

Terminal window
curl -I https://example-app.klutch.sh/rest/health

Create a short URL (replace API_KEY with your Shlink API key):

Terminal window
curl -X POST https://example-app.klutch.sh/rest/v3/short-urls \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: API_KEY" \
  -d '{"longUrl":"https://klutch.sh","validateUrl":true}'

Health checks and production tips

  • Add an HTTP readiness probe to /rest/health.
  • Keep DB credentials, API keys, and geolocation keys in Klutch.sh secrets; rotate regularly.
  • Pin image versions and test upgrades in staging before production rollout.
  • Back up your external database; export /etc/shlink if you store local config/logs.

Shlink on Klutch.sh delivers reproducible Docker builds, managed secrets, and optional config storage—without extra YAML or CI steps. Configure ports, env vars, and storage, then launch your private link shortener.