YOURLS mit Docker Compose und MariaDB selbst hosten: eigener URL-Shortener mit API, Backup und Update

Kurzlinks für Newsletter, Flyer, QR-Codes oder Support-Mails landen bei Cloud-Diensten, die jeden Klick auswerten und Links nach Ablauf eines Tarifs abschalten können. YOURLS (Your Own URL Shortener) ist ein schlanker, quelloffener URL-Shortener in PHP unter MIT-Lizenz: Kurzlinks mit eigener Domain, Klickstatistik, Plugins und eine HTTP-API. Das Projekt hat auf GitHub gut 12.000 Sterne, aktuell ist Version 1.10.6 vom 30.08.2026. Diese Anleitung installiert YOURLS mit dem offiziellen Docker-Image und MariaDB, richtet die API mit Signatur-Token ein, sichert die Datenbank, stellt sie nach einem Totalverlust wieder her und zeigt ein echtes Update von 1.10.4 auf 1.10.6.

Voraussetzungen

YOURLS ist genügsam: Apache mit PHP im App-Container und eine MariaDB. Für ein Team oder eine Firmen-Kurzdomain reicht ein kleiner Server.

• Linux-Server (x86_64 oder ARM64) mit 1 bis 2 vCPU, 2 GB RAM und 5 GB freiem Speicher
• Docker Engine mit Compose-Plugin (docker compose version)
• eine eigene, möglichst kurze Domain oder Subdomain, etwa kurz.example.de, mit DNS-Eintrag auf den Server
• ein Reverse Proxy mit TLS (Caddy, Nginx, Traefik oder Nginx Proxy Manager) für den Betrieb im Internet
• Grundkenntnisse in Shell und Compose

Eckdaten

Punkt	Wert
App-Image	yourls:1.10.6-apache (offizielles Docker-Hub-Image, Apache 2.4 mit PHP 8.5)
Datenbank	mariadb:11.8.9
Port	Container 8080 (HTTP)
Volumes	yourls_user auf /var/www/html/user (config.php, Plugins), db_data auf /var/lib/mysql
Pflicht-Variablen	YOURLS_SITE, YOURLS_USER, YOURLS_PASS, YOURLS_DB_HOST, YOURLS_DB_USER, YOURLS_DB_PASS
Lizenz	MIT

Das Tag latest zeigt ebenfalls auf 1.10.6 mit Apache. Schreiben Sie trotzdem die Version fest, damit ein Update eine bewusste Entscheidung bleibt.

Schritt 1: Projektordner, compose.yaml und .env

sudo mkdir -p /opt/yourls && cd /opt/yourls

Die compose.yaml:

services:
  yourls:
    image: yourls:${YOURLS_TAG:-1.10.6-apache}
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8080:8080"
    environment:
      YOURLS_SITE: ${YOURLS_SITE}
      YOURLS_USER: ${YOURLS_USER}
      YOURLS_PASS: ${YOURLS_PASS}
      YOURLS_DB_HOST: db
      YOURLS_DB_NAME: yourls
      YOURLS_DB_USER: yourls
      YOURLS_DB_PASS: ${DB_PASS}
    volumes:
      - yourls_user:/var/www/html/user

  db:
    image: mariadb:11.8.9
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: yourls
      MARIADB_USER: yourls
      MARIADB_PASSWORD: ${DB_PASS}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASS}
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10

volumes:
  yourls_user:
  db_data:

Die .env erzeugen Sie mit Zufallswerten:

cat > .env <<EOF
YOURLS_TAG=1.10.6-apache
YOURLS_SITE=https://kurz.example.de
YOURLS_USER=admin
YOURLS_PASS=$(openssl rand -hex 12)
DB_PASS=$(openssl rand -hex 16)
DB_ROOT_PASS=$(openssl rand -hex 16)
EOF
chmod 600 .env

Drei Punkte sind wichtig. YOURLS_SITE ist die öffentliche Adresse ohne abschließenden Schrägstrich, klein geschrieben; YOURLS baut daraus jeden Kurzlink. Das Volume auf user/ enthält die beim ersten Start erzeugte config.php samt zufälligem Cookie-Schlüssel, von dem das Signatur-Token abhängt. Und das Datenbankpasswort wirkt nur beim allerersten Start der MariaDB, spätere Änderungen in der .env ändern das Passwort in der Datenbank nicht. Hinter einem Reverse Proxy binden Sie den Port besser an 127.0.0.1:8080:8080.

Verifizieren: docker compose config --quiet gibt nichts aus, die Datei ist also gültig.

Schritt 2: Stack starten und YOURLS installieren

docker compose up -d
docker compose ps
docker compose logs yourls | tail -5

Beim ersten Start kopiert der Container YOURLS nach /var/www/html und meldet Complete! YOURLS has been successfully copied to /var/www/html. Die App wartet dank Healthcheck, bis MariaDB bereit ist. Ein Aufruf von /admin/ leitet anschließend mit HTTP 307 auf /admin/install.php um. Dort genügt ein Klick auf Install YOURLS. Ohne Browser geht es auch per curl:

curl -s -X POST -d install=1 http://localhost:8080/admin/install.php \
  | sed -e 's/<[^>]*>/ /g' | grep -E "created|successfully"

Im Test meldete YOURLS die Tabellen yourls_url, yourls_options und yourls_log sowie YOURLS tables successfully created. Die Wurzel der Domain antwortet ohne eigene Startseite mit 403, das ist normal.

Verifizieren: In der Datenbank steht die Version:

docker compose exec db sh -c 'mariadb -uyourls -p"$MARIADB_PASSWORD" yourls \
  -e "select option_name, option_value from yourls_options"'

Erwartet werden version 1.10.6 und db_version 507.

Schritt 3: Anmelden und erste Kurzlinks anlegen

Melden Sie sich unter https://kurz.example.de/admin/ mit YOURLS_USER und YOURLS_PASS an. Die Instanz ist standardmäßig privat (YOURLS_PRIVATE ist im Container-Config wahr), nur angemeldete Benutzer dürfen kürzen. Ins Feld Enter the URL tragen Sie das Ziel ein, unter Custom short URL optional ein eigenes Kürzel.

Bindestriche in Kürzeln entfernt YOURLS ohne Plugin: Aus nl-oktober wurde im Test nloktober. Wer Bindestriche braucht, aktiviert unter Manage Plugins das mitgelieferte Plugin Hyphens in URLs. Die Kürzel sind standardmäßig klein geschrieben (YOURLS_URL_CONVERT 36); legen Sie das vor dem ersten Link fest und ändern Sie es danach nicht mehr.

Verifizieren: curl -sI http://localhost:8080/IHRKUERZEL liefert HTTP/1.1 301 und den Ziel-Link im Location-Header. Unbekannte Kürzel leiten mit 302 auf die Startadresse um.

Schritt 4: API mit Signatur-Token nutzen

Die API liegt unter /yourls-api.php und akzeptiert GET oder POST. Benutzer und Passwort funktionieren, gehören aber nicht in Skripte. Auf der Seite Tools finden Sie ein geheimes Signatur-Token, das nur für die API gilt und keine Anmeldung an der Oberfläche erlaubt.

SIG='IHR_SIGNATUR_TOKEN'
curl -s "http://localhost:8080/yourls-api.php" \
  -d signature=$SIG -d action=shorturl \
  -d url=https://example.org/handbuch -d keyword=handbuch -d format=json

Die Antwort enthält "status":"success" und das Feld shorturl. Weitere Aktionen sind expand, url-stats, stats und db-stats. Ein zweiter Versuch mit derselben Ziel-URL scheitert, weil YOURLS_UNIQUE_URLS standardmäßig aktiv ist. Achtung bei Skripten: Version 1.10.4 antwortete darauf mit HTTP 400, Version 1.10.6 im Test mit HTTP 409 und already exists in database.

Falsche Zugangsdaten beantwortet YOURLS mit HTTP 403: bei Benutzer und Passwort mit Invalid username or password, bei einem falschen Token mit Please log in.

Verifizieren: curl -s "http://localhost:8080/yourls-api.php?signature=$SIG&action=url-stats&shorturl=handbuch&format=json" liefert "statusCode":"200" und den Zähler clicks.

Schritt 5: Klickstatistik auswerten

Jeder Aufruf eines Kurzlinks erhöht den Zähler, im Test auch Aufrufe per curl ohne Browser-Kennung. Hängen Sie ein Pluszeichen an das Kürzel (/sedv+), öffnet YOURLS die Statistikseite mit Verlauf, Herkunftsländern und Verweisen.

Ein Fallstrick betrifft Docker: Als IP sah YOURLS im Test bei allen Links das Gateway des Docker-Netzes (172.18.0.1), nicht den Besucher. Hinter einem Reverse Proxy liest YOURLS die echte Adresse aus X-Forwarded-For erst, wenn Sie die Proxy-Adressen per Plugin über den Filter get_ip_trusted_proxies als vertrauenswürdig eintragen. Ohne diesen Schritt sind Länder-Statistik und Flood-Schutz wenig aussagekräftig.

Verifizieren: Die API-Aktion stats mit filter=top&limit=5 listet die meistgeklickten Links mit Summe total_clicks.

Schritt 6: Backup mit mariadb-dump

Alle Links und Klicks liegen in MariaDB. Die Programmdateien kommen aus dem Image, das Volume yourls_user enthält config.php (mit Cookie-Schlüssel) und eventuelle Plugins. Sichern Sie beides:

cd /opt/yourls && mkdir -p backup
docker compose exec -T db sh -c 'mariadb-dump -uroot -p"$MARIADB_ROOT_PASSWORD" \
  --single-transaction --routines --databases yourls' \
  | gzip > backup/yourls-db-$(date +%F).sql.gz
docker compose cp yourls:/var/www/html/user backup/user-$(date +%F)
cp .env backup/

--single-transaction erzeugt einen konsistenten Stand ohne Sperren, --databases schreibt CREATE DATABASE in den Dump, damit der Restore auch eine gelöschte Datenbank wieder anlegt. Planen Sie das per Cron oder systemd-Timer und kopieren Sie die Dateien auf ein anderes System.

Verifizieren: zcat backup/yourls-db-*.sql.gz | grep -c "INSERT INTO" muss größer als null sein, und ein bekanntes Kürzel muss im Dump auftauchen.

Schritt 7: Restore nach Totalverlust

Im Test legten wir einen Marker-Link marker an, sicherten die Datenbank und löschten sie danach komplett mit DROP DATABASE yourls. Ein Aufruf des Markers ergab daraufhin HTTP 503 mit Fatal error Incorrect DB config, or could not connect to DB und [1049] Unknown database 'yourls'. So stellen Sie wieder her:

docker compose stop yourls
zcat backup/yourls-db-DATUM.sql.gz | docker compose exec -T db \
  sh -c 'mariadb -uroot -p"$MARIADB_ROOT_PASSWORD"'
docker compose start yourls

Stoppen Sie die App vorher, damit während des Imports keine Klicks in halbfertige Tabellen geschrieben werden. Der Import endete im Test mit Exit-Code 0, alle neun Links waren zurück, und der Marker leitete wieder mit 301 auf sein Ziel weiter. Auch die Klickzähler stimmten mit dem Stand vor der Löschung überein. Bei einem Umzug auf einen neuen Server spielen Sie zusätzlich die gesicherte config.php per docker compose cp in das Volume, sonst erzeugt der Container einen neuen Cookie-Schlüssel und damit ein neues Signatur-Token.

Verifizieren: curl -sI http://localhost:8080/marker zeigt wieder 301 und die erwartete Location.

Schritt 8: Update auf eine neue Version

Getestet haben wir den Weg von 1.10.4 auf 1.10.6. Vor dem Update sichern Sie wie in Schritt 6, dann ändern Sie das Tag und ziehen das neue Image:

sed -i 's/^YOURLS_TAG=.*/YOURLS_TAG=1.10.6-apache/' .env
docker compose pull yourls
docker compose up -d
docker compose exec yourls grep YOURLS_VERSION /var/www/html/includes/version.php

Der Container übernimmt die vorhandene config.php aus dem Volume, die Datenbank blieb bei db_version 507, die Option version stand anschließend auf 1.10.6, und alle Links leiteten weiter. Zwei Dinge sollten Sie einplanen: Bestehende Sitzungen waren nach dem Update ungültig, alle Benutzer müssen sich neu anmelden. Und das Signatur-Token auf der Seite Tools war ein anderes, länger als vorher; Aufrufe mit dem alten Token scheiterten mit Please log in. Das fällt in die Sicherheitshärtung von 1.10.5, die laut Changelog MD5 beim passwortlosen API-Zugang ablöst, ohne bestehende Installationen zu brechen; im Test war das alte Token trotzdem ungültig. Tragen Sie das neue Token deshalb direkt nach dem Update in alle Skripte und Integrationen ein. 1.10.6 selbst korrigiert nur die Versionsangabe von 1.10.5.

Verifizieren: Die Fußzeile der Adminoberfläche zeigt YOURLS v 1.10.6, ein API-Aufruf mit dem neuen Token liefert 200.

Troubleshooting

Alle folgenden Meldungen haben wir im Test absichtlich ausgelöst.

• [2002] php_network_getaddresses: getaddrinfo for db failed: Der Datenbank-Container läuft nicht oder heißt anders als YOURLS_DB_HOST. Prüfen Sie docker compose ps und starten Sie db.
• [1045] Access denied for user 'yourls': Das Passwort in der .env passt nicht mehr zur Datenbank, meist nach einer nachträglichen Änderung von DB_PASS. Alten Wert zurücksetzen oder das Passwort in MariaDB per ALTER USER ändern.
• [1049] Unknown database 'yourls' und HTTP 503: Datenbank fehlt. Restore wie in Schritt 7.
• Kurzlinks zeigen auf http://localhost:8080/: YOURLS_SITE ist falsch gesetzt. Im Test mit falschem Wert erhielt ein neuer Link die Adresse http://localhost:8080/1, und CSS wurde von localhost geladen. Wert korrigieren, docker compose up -d; bereits erzeugte Kürzel bleiben gültig, weil nur das Kürzel gespeichert wird.
• API antwortet 403 Please log in: falsches oder nach einem Update veraltetes Signatur-Token. Neues Token von der Seite Tools übernehmen.
• Doppelte Ziel-URL abgelehnt: HTTP 409 ab 1.10.5, vorher 400. Bei Bedarf YOURLS_UNIQUE_URLS=false setzen.
• Alle Klicks mit derselben IP: Docker-Gateway oder Proxy, siehe Schritt 5.

Häufige Fragen

Brauche ich die Variante fpm statt apache?

Nur wenn bereits ein Webserver mit FastCGI davor steht. Die fpm-Variante darf laut Image-Dokumentation nie direkt per Port veröffentlicht werden. Für einen eigenständigen Dienst ist apache einfacher.

Kann ich YOURLS öffentlich nutzbar machen?

Technisch ja, über YOURLS_PRIVATE=false. Ein offener Shortener wird aber schnell für Spam und Phishing missbraucht. Für Firmen bleibt die private Instanz die richtige Wahl.

Wie unterscheidet sich YOURLS von Kutt oder Shlink?

YOURLS ist das älteste und schlankste Projekt mit klassischer PHP-Oberfläche und großem Plugin-Angebot. Kutt bietet eine moderne Oberfläche mit Benutzerkonten, Shlink setzt auf API und mehrere Domains.

Wo stelle ich die Zeitzone ein?

Über die Variable YOURLS_HOURS_OFFSET als Abstand zu GMT, für Deutschland im Winter 1.

Fazit

YOURLS ist in wenigen Minuten einsatzbereit und braucht kaum Ressourcen. Die Installation über install.php, Kurzlinks per API, Statistik, Backup und Restore funktionierten im Test ohne Umwege. Planen Sie zwei Dinge bewusst ein: die echte Besucher-IP hinter Docker und einem Proxy, und das neue Signatur-Token nach dem Update auf 1.10.5 oder neuer. Wer beides im Griff hat und die Datenbank regelmäßig sichert, betreibt einen verlässlichen Kurzlink-Dienst unter eigener Domain.

Weiterführende Anleitungen und Quellen

• Kutt: URL-Shortener mit Docker Compose, API, Statistik und Backup
• Shlink: URL-Kürzer mit Docker Compose und MariaDB selbst hosten
• Große Datenbanken mit mariadb-dump exportieren und importieren
• YOURLS auf GitHub
• Release-Notizen YOURLS 1.10.5
• Offizielles Docker-Image yourls
• YOURLS-Dokumentation: API
• YOURLS-Dokumentation: Passwordless API
• YOURLS-Dokumentation: Proxy und Trusted Proxies