SSD Nodes Learn Hosting plans →
Gidsen Matt ConnorDoor Matt Connor · Bijgewerkt 2026-11-20

Zelf een URL-verkorter hosten met Shlink en Docker

Host uw eigen URL-verkorter op een VPS met Shlink en Docker Compose. Leer hoe u een kort domein koppelt, Postgres configureert en klikstatistieken beheert voor Shlink 5.1.

Wat u gaat bouwen

Een zelfgehoste URL-verkorter is een kleine server die een lange link omzet in een korte link die uw eigendom is, en die elke klik daarop telt. Shlink is de juiste keuze: het is open source, wordt geleverd als Docker-image en voert de volledige taak uit in één container plus een database. Deze handleiding plaatst de software op een VPS achter een eigen kort domein, met HTTPS, een API-sleutel, QR-codes en klikstatistieken.

Twee onderdelen zorgen ervoor dat het aanvoelt als een commerciële verkorter. De API-server handelt redirects af en beheert de gegevens. De webclient is een afzonderlijke statische applicatie die vanuit uw browser met die API communiceert. U kunt beide draaien, of alleen de API gebruiken en deze aansturen via de command line.

De versienummers in deze handleiding zijn actueel op 19 november 2026: Shlink 5.1.8 en shlink-web-client 4.9.0.

Wijs eerst een kort domein naar de server

Het domein is het product. s.example.com/abc123 is de link die gebruikers zien, dus kies een korte naam en leg deze vast voordat u met de installatie begint. Shlink koppelt elke korte URL aan het standaarddomein of een specifiek toegewezen domein. Als u dit later wijzigt, moet u het oude domein naar Shlink laten wijzen om te zorgen dat reeds gedeelde links blijven werken.

Maak één DNS A-record aan voor het korte domein dat naar het publieke IPv4-adres van uw VPS wijst. Voeg ook een AAAA-record toe als de server over IPv6 beschikt. Controleer of het domein correct resolveert voordat u verdergaat.

dig +short s.example.com A

De output moet het adres van uw server zijn. Als de output leeg is, is het record nog niet verspreid. Elke volgende stap zal dan op onduidelijke wijze falen, omdat er geen TLS (transport layer security)-certificaat kan worden uitgegeven voor een naam die niet resolveert.

Het compose-bestand

Shlink heeft een database nodig. SQLite volstaat voor een test, maar Postgres is de juiste keuze voor alles wat u wilt behouden. Aantal bezoeken loopt namelijk op en Postgres verwerkt indexen en gelijktijdige schrijfacties beter. Plaats dit in /opt/shlink/compose.yaml.

services:
  shlink:
    image: shlinkio/shlink:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      DEFAULT_DOMAIN: s.example.com
      IS_HTTPS_ENABLED: "true"
      DB_DRIVER: postgres
      DB_HOST: database
      DB_NAME: shlink
      DB_USER: shlink
      DB_PASSWORD: ${DB_PASSWORD}
    depends_on:
      - database

  database:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: shlink
      POSTGRES_USER: shlink
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - shlink_db:/var/lib/postgresql/data

  web-client:
    image: shlinkio/shlink-web-client:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:8081:8080"

volumes:
  shlink_db:

Beide gepubliceerde poorten binden aan 127.0.0.1, waardoor niets bereikbaar is vanaf het internet totdat de reverse proxy in de volgende sectie is geplaatst. Docker schrijft zijn eigen doorstuurregels vóór de firewall van de host, wat betekent dat een eenvoudige 8080:8080-regel de applicatie zou blootstellen, zelfs op een server waarvan de firewall gesloten lijkt. Binden aan het loopback-adres voorkomt dit. Hetzelfde patroon is van toepassing op elke applicatie die u op deze manier uitvoert, en dit wordt in meer detail behandeld in de handleiding voor Docker Compose op een VPS.

Het databasewachtwoord komt uit een .env-bestand naast het compose-bestand, zodat het nooit in de YAML terechtkomt.

sudo mkdir -p /opt/shlink
printf 'DB_PASSWORD=%s\n' "$(openssl rand -base64 24)" | sudo tee /opt/shlink/.env
sudo chmod 600 /opt/shlink/.env

Start het en wacht tot de API beschikbaar is.

cd /opt/shlink
sudo docker compose up -d
sudo docker compose logs -f shlink

De eerste start voert de databasemigraties uit, waardoor dit langer duurt dan bij latere starts. Controleer zodra het proces stabiel is of de service lokaal antwoordt.

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/rest/health

Een 200 betekent dat de API actief is en de databaseverbinding werkt. Een 503 betekent dat Shlink draait, maar dat de databasecontrole is mislukt. Het health-endpoint antwoordt met 503 bij elke databasefout, nooit met 500. Als curl 000 afdrukt, heeft het geen HTTP-antwoordcode ontvangen; controleer de connectiviteit en de bovenstaande logs voordat u concludeert dat de container is gestopt of opnieuw opstart. Als de logs een database-authenticatiefout tonen, controleer dan of de DB_PASSWORD in .env overeenkomt met de gegevens waarmee Postgres is aangemaakt, omdat de Postgres-image POSTGRES_PASSWORD alleen leest wanneer deze een lege datamap initialiseert. Het later bewerken van .env wijzigt het bestaande databasewachtwoord niet; wijzig ook het wachtwoord van de database-rol of plaats het bestaande wachtwoord terug in .env.

HTTPS-terminatie aan de voorzijde

Shlink serveert standaard HTTP op poort 8080. TLS hoort thuis in een reverse proxy, waarbij de belangrijkste instelling het doorgeven van de oorspronkelijke hostnaam is. Shlink gebruikt de Host-header om short codes op te zoeken, met een fallback naar het matchen van links op het standaarddomein. Een herschreven hostnaam kan er daarom voor zorgen dat de verkeerde link wordt geselecteerd of dat een 404-foutmelding verschijnt voor een code die alleen op een ander domein bestaat.

server {
    server_name s.example.com;
    listen 80;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Vraag vervolgens het certificaat aan. De volledige handleiding, inclusief de timer voor vernieuwing, vindt u in de Certbot-handleiding voor nginx op Ubuntu 24.04.

sudo certbot --nginx -d s.example.com

IS_HTTPS_ENABLED: "true" in het compose-bestand zorgt ervoor dat Shlink https:// afdrukt in de korte URL's die het teruggeeft. Dit activeert niet uit zichzelf TLS. Laat dit false achter een HTTPS-proxy en elke link die de API teruggeeft is een http://-link die vervolgens doorverwijst. Dit kost een extra round trip en ziet er onjuist uit in de webclient.

Een API-key aanmaken

De management-API vereist een key; het health-endpoint is openbaar. Genereer een key via de CLI binnen de container.

sudo docker compose exec shlink shlink api-key:generate --name "web client"

Het commando toont de key slechts eenmaal. Kopieer deze direct, aangezien de key gehasht wordt opgeslagen en niet opnieuw kan worden weergegeven. shlink api-key:list toont de namen en of elke key is ingeschakeld, maar nooit de key zelf. Trek een key in met shlink api-key:disable en de naam.

Stuur de key mee in een X-Api-Key-header voor REST-managementaanroepen.

curl -H "X-Api-Key: YOUR_KEY" https://s.example.com/rest/v3/short-urls

Een JSON-object met een shortUrls-key betekent dat de key correct werkt. Een 401 waarvan de type gelijk is aan https://shlink.io/api/error/invalid-api-key, met de titel Invalid API key, betekent dat de key onjuist is, is uitgeschakeld of de vervaldatum is verstreken.

De CLI is de snelste manier om links aan te maken en is uitermate geschikt voor scripting.

sudo docker compose exec shlink shlink short-url:create https://example.com/a/very/long/path
sudo docker compose exec shlink shlink short-url:create https://example.com/docs --custom-slug docs --tag reference

--custom-slug geeft u een leesbare link in plaats van een gegenereerde code. Slugs zijn uniek per domein; een tweede poging met een reeds gebruikte slug mislukt daarom in plaats van de eerste link stilletjes te overschrijven. --tag kan worden herhaald, en met tags groepeert u links waarvan u later gecombineerde statistieken wilt inzien.

Bekijk welke links bestaan en analyseer vervolgens het verkeer van één specifieke link.

sudo docker compose exec shlink shlink short-url:list
sudo docker compose exec shlink shlink short-url:visits docs

short-url:visits toont één rij per klik met de datum, de referrer en de user agent. De kolommen voor land en stad blijven leeg tenzij u een GEOLITE_LICENSE_KEY omgevingsvariabele instelt; dit is een gratis MaxMind-sleutel die Shlink gebruikt om de GeoLite2-database te downloaden. Zonder deze sleutel worden bezoeken nog steeds geregistreerd, maar ze worden simpelweg niet geografisch gelokaliseerd.

De webclient en QR-codes

De webclient bevindt zich nu op 127.0.0.1:8081 en heeft een eigen proxy-entry nodig, of een SSH-tunnel als u deze liever niet publiceert. Bij de eerste keer laden wordt er gevraagd om een server-URL en een API-sleutel. Voer https://s.example.com en de door u gegenereerde sleutel in. De client bewaart beide in de browseropslag en roept uw API rechtstreeks aan, waardoor er geen gegevens via derden verlopen. Het scheiden van de interface van de API is een patroon dat het opmerken waard is; het is hetzelfde patroon waarmee Halcyon een Jellyfin-bibliotheek presenteert als een videotheek uit de jaren 90 zonder de mediaserver erachter te wijzigen.

QR-codes worden gegenereerd door de webclient, niet door de API. Shlink 5 heeft de oude methode verwijderd waarbij /qr-code aan een korte URL werd toegevoegd; dat adres geeft dus geen afbeelding meer terug. De webclient tekent de code in uw browser, zonder een verzoek naar Shlink te sturen. Open de QR-code-optie bij een willekeurige link in de lijst met korte URL's, stel de grootte, het formaat en de marge in en download het resultaat. Verhoog het foutcorrectieniveau voor een code die nog steeds scanbaar moet zijn wanneer deze klein wordt afgedrukt of gedeeltelijk is bedekt. Hetzelfde dialoogvenster ondersteunt ook kleuren en een logo.

Operationeel houden

Een URL-shortener faalt vaak onopgemerkt. De links stoppen met doorverwijzen en u krijgt geen melding, omdat de gebruiker die op de link klikt ervan uitgaat dat de link simpelweg dood is. Richt een uptime-controle in op een daadwerkelijke korte URL in plaats van op de startpagina, en stel een waarschuwing in voor elke status die geen redirect is. Een zelfgehoste Uptime Kuma-instantie voert dit goed uit en kan controleren op een specifieke statuscode.

Maak een back-up van de database, niet van de container. Eén commando volstaat voor de dump.

sudo docker compose exec -T database pg_dump -U shlink shlink | gzip > shlink-$(date +%F).sql.gz

Dat bestand, samen met uw compose-bestand en .env, bouwt de volledige service opnieuw op een nieuwe server. Elke applicatie op de server heeft zijn eigen versie van die back-up nodig. Een fotobibliotheek is hierbij een lastig geval, omdat PhotoPrism en Immich beide de originelen op schijf bewaren, naast rijen in een database. Een dump alleen herstelt dus wel de databaserecords, maar niet de foto's zelf of de op bestanden gebaseerde instellingen van PhotoPrism. Maak ook een back-up van de configuratie van PhotoPrism, inclusief het bestand settings.yml dat de voorkeuren voor de gebruikersinterface, downloads en indexering bevat. Upgrades voert u uit met sudo docker compose pull gevolgd door sudo docker compose up -d; Shlink voert bij het opstarten automatisch alle nieuwe migraties uit. Maak de dump voordat u de nieuwe versie ophaalt, aangezien een migratie niet ongedaan kan worden gemaakt.

FAQ

Shlink vergelijkt een short code met het domein in de Host-header. Als de proxy een ander hostadres meestuurt, controleert Shlink dat domein en valt vervolgens terug op een overeenkomende link in het standaarddomein; het systeem geeft een 404 als geen van beide de code bevat. Stel proxy_set_header Host $host; in het nginx location-blok in en herlaad de proxy. De links werken direct, zonder dat de container opnieuw hoeft te worden opgestart.

Heb ik Postgres nodig, of is SQLite voldoende?

SQLite is prima om Shlink uit te proberen en vereist geen tweede container. Stap over op Postgres voordat u belangrijke links publiceert, omdat het aantal rijen met bezoekers bij elke klik groeit en SQLite schrijfacties serialiseert. Later overstappen betekent dat u uw links moet exporteren en opnieuw importeren, dus kiezen voor Postgres vanaf het begin bespaart u die migratie.

Kan ik een API-key herstellen die ik vergeten ben te kopiëren?

Nee. Shlink slaat een hash van de key op, dus api-key:list toont namen en status, maar nooit de waarde zelf. Genereer een vervangende key met shlink api-key:generate, plak deze in de webclient en schakel vervolgens de oude key uit met shlink api-key:disable zodat deze niet langer werkt.

Waarom zijn de kolommen voor landen leeg in mijn bezoekersstatistieken?

Geolocatie vereist de GeoLite2-database, die Shlink alleen downloadt wanneer u een GEOLITE_LICENSE_KEY opgeeft. De key is gratis verkrijgbaar bij MaxMind. Voeg deze toe aan de environment-sectie, maak de container opnieuw aan en nieuwe bezoeken worden gelokaliseerd. Bezoeken die vóór dat moment zijn geregistreerd, blijven leeg totdat u shlink visit:locate uitvoert.

Behoud het domein en verplaats de data. Maak een dump van de database met pg_dump, kopieer de dump, het compose-bestand en .env naar de nieuwe server, start alleen de database, herstel de dump in de lege database en start vervolgens Shlink en de webclient voordat er echt verkeer binnenkomt. Wijzig het DNS-record als laatste. De short codes en hun bezoekersgeschiedenis blijven behouden, omdat alles in de database staat.

Was dit artikel nuttig?

#shlink#url-shortener#self-hosting#docker#postgres