Installer un raccourcisseur d’URL avec Shlink et Docker
Installez Shlink 5.1 sur un VPS avec Docker Compose : domaine court, HTTPS, PostgreSQL, clé d’API, client web, QR codes et statistiques de clics.
Ce que vous allez construire
Un raccourcisseur d’URL auto-hébergé est un petit serveur qui transforme un lien long en lien court dont vous êtes propriétaire et compte chaque clic. Shlink est un bon choix : il est open source, est distribué sous forme d’image Docker et fait tout le travail avec un conteneur et une base de données. Ce guide l’installe sur un VPS derrière un véritable domaine court, avec HTTPS, une clé API, des QR codes et des statistiques de clics.
Deux composants lui donnent le fonctionnement d’un raccourcisseur commercial. Le serveur API répond aux redirections et conserve les données. Le client web est une application statique distincte qui communique avec cette API depuis votre navigateur. Vous pouvez exécuter les deux, ou exécuter uniquement l’API et la piloter depuis la ligne de commande.
Les numéros de version indiqués ici correspondent aux versions disponibles au 19 novembre 2026 : Shlink 5.1.8 et shlink-web-client 4.9.0.
Pointez d’abord un domaine court vers le serveur
Le domaine est le produit. s.example.com/abc123 est le lien que les utilisateurs voient. Choisissez donc un nom court avant d’installer quoi que ce soit. Shlink associe chaque URL courte au domaine par défaut ou à un domaine attribué explicitement. Si vous le changez plus tard, vous devrez continuer à pointer l’ancien domaine vers Shlink pour que les liens déjà distribués restent fonctionnels.
Créez un enregistrement DNS de type A pour le domaine court. Faites-le pointer vers l’adresse IPv4 publique de votre VPS. Ajoutez également un enregistrement AAAA si le serveur dispose d’IPv6. Vérifiez ensuite que le domaine se résout avant de continuer.
dig +short s.example.com ALa sortie doit être l’adresse de votre serveur. Si elle est vide, l’enregistrement ne s’est pas encore propagé. Toutes les étapes suivantes échoueront alors d’une manière difficile à diagnostiquer, car il est impossible d’émettre un certificat TLS (transport layer security) pour un nom qui ne se résout pas.
Le fichier Compose
Shlink a besoin d’une base de données. SQLite convient pour un test, mais Postgres est le bon choix pour toute installation que vous comptez conserver, car les lignes de visites s’accumulent et Postgres gère mieux les index et les écritures concurrentes. Placez ceci dans /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:Les deux ports publiés sont liés à 127.0.0.1. Rien n’est donc accessible depuis Internet tant que le reverse proxy de la section suivante n’est pas en place. Docker écrit ses propres règles de transfert avant celles du pare-feu de l’hôte. Une simple règle 8080:8080 exposerait donc l’application même si le pare-feu de la machine semble fermé. La liaison à l’adresse loopback évite ce problème. Le même principe s’applique à toutes les applications que vous exécutez ainsi. Il est expliqué plus en détail dans le guide consacré à Docker Compose sur un VPS.
Le mot de passe de la base de données provient d’un fichier .env placé à côté du fichier Compose. Il ne se retrouve donc jamais dans le YAML.
sudo mkdir -p /opt/shlink
printf 'DB_PASSWORD=%s\n' "$(openssl rand -base64 24)" | sudo tee /opt/shlink/.env
sudo chmod 600 /opt/shlink/.envDémarrez-le et surveillez le démarrage de l’API.
cd /opt/shlink
sudo docker compose up -d
sudo docker compose logs -f shlinkLe premier démarrage exécute les migrations de la base de données. Il prend donc plus de temps que les suivants. Une fois le service stabilisé, vérifiez qu’il répond localement.
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/rest/healthUn 200 signifie que l’API est active et que la connexion à la base de données fonctionne. Un 503 signifie que Shlink fonctionne, mais que la vérification de la base de données a échoué. Le endpoint de santé renvoie 503 pour toute erreur de base de données, jamais 500. Si curl affiche plutôt 000, il n’a reçu aucun code de réponse HTTP. Vérifiez la connectivité et les journaux ci-dessus avant de conclure que le conteneur s’est arrêté ou redémarre. Si les journaux indiquent un échec d’authentification de la base de données, vérifiez que le DB_PASSWORD dans .env correspond à celui utilisé lors de la création de Postgres, car l’image Postgres ne lit POSTGRES_PASSWORD que lorsqu’elle initialise un répertoire de données vide. Modifier .env par la suite ne change pas le mot de passe existant de la base de données. Modifiez également le mot de passe du rôle de base de données, ou remettez l’ancien mot de passe dans .env.
Terminer HTTPS en amont
Shlink fournit du HTTP non chiffré sur le port 8080. TLS doit être géré par un reverse proxy. Le point essentiel consiste à transmettre le nom d’hôte d’origine. Shlink utilise l’en-tête Host pour rechercher les codes courts. Il peut aussi rechercher les liens correspondants sur le domaine par défaut. Un hôte réécrit peut donc sélectionner le mauvais lien ou renvoyer 404 pour un code qui n’existe que sur un autre domaine.
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;
}
}Émettez ensuite le certificat. La procédure complète, y compris le timer de renouvellement, se trouve dans le guide Certbot pour nginx sur Ubuntu 24.04.
sudo certbot --nginx -d s.example.comDans le fichier compose, IS_HTTPS_ENABLED: "true" indique à Shlink d’inclure https:// dans les URL courtes qu’il renvoie. Cette option n’active pas TLS à elle seule. Laissez-la false derrière un proxy HTTPS. Ainsi, chaque lien renvoyé par l’API est un lien http:// qui effectue ensuite une redirection. Cela ajoute un aller-retour et donne un résultat incorrect dans le client web.
Créer une clé API
L’API de gestion nécessite une clé ; le endpoint de santé est public. Générez-en une via la CLI dans le conteneur.
sudo docker compose exec shlink shlink api-key:generate --name "web client"La commande affiche la clé une seule fois. Copiez-la maintenant, car elle est stockée sous forme de hash et ne peut plus être affichée. shlink api-key:list affiche les noms et indique si chaque clé est activée, mais jamais la clé elle-même. Révoquez une clé avec shlink api-key:disable et son nom.
Envoyez la clé dans un en-tête X-Api-Key pour les appels REST de gestion.
curl -H "X-Api-Key: YOUR_KEY" https://s.example.com/rest/v3/short-urlsUn objet JSON contenant une clé shortUrls indique que la clé fonctionne. Un 401 dont le type est https://shlink.io/api/error/invalid-api-key, avec le titre Invalid API key, indique que la clé est incorrecte, désactivée ou arrivée à expiration.
Créer des liens courts depuis la ligne de commande
La CLI est le moyen le plus rapide de créer des liens. C’est aussi celui qui s’intègre le mieux aux scripts.
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 vous fournit un lien lisible au lieu d’un code généré. Les slugs sont uniques par domaine : une seconde tentative avec un slug déjà utilisé échoue au lieu d’écraser silencieusement le premier lien. --tag peut être répété. Les tags permettent de regrouper les liens pour lesquels vous voudrez obtenir des statistiques combinées ultérieurement.
Listez les éléments existants, puis consultez le trafic d’un lien.
sudo docker compose exec shlink shlink short-url:list
sudo docker compose exec shlink shlink short-url:visits docsshort-url:visits affiche une ligne par clic, avec la date, le referer et le user agent. Les colonnes du pays et de la ville restent vides tant que vous n’avez pas défini une variable d’environnement GEOLITE_LICENSE_KEY. Il s’agit d’une clé MaxMind gratuite que Shlink utilise pour télécharger la base de données GeoLite2. Sans cette clé, les visites sont tout de même enregistrées, mais elles ne sont pas géolocalisées.
Le client web et les codes QR
Le client web est maintenant disponible sur 127.0.0.1:8081. Il nécessite sa propre entrée de proxy, ou un tunnel SSH si vous préférez ne pas le publier. Au premier chargement, il demande l’URL du serveur et une clé d’API. Saisissez https://s.example.com et la clé que vous avez générée. Le client conserve ces deux éléments dans le stockage du navigateur et appelle directement votre API. Aucune donnée ne transite donc par un tiers. La séparation de l’interface et de l’API est un modèle intéressant à retenir. C’est le même modèle qui permet à Halcyon de présenter une bibliothèque Jellyfin comme un vidéoclub des années 1990 sans modifier le serveur multimédia sous-jacent.
Les codes QR sont générés par le client web, pas par l’API. Shlink 5 a supprimé l’ancienne possibilité d’ajouter /qr-code à une URL courte. Cette adresse ne renvoie donc plus d’image. Le client web génère désormais le code dans votre navigateur, sans envoyer de requête à Shlink. Ouvrez l’option de code QR sur n’importe quel lien de la liste des URL courtes, définissez la taille, le format et la marge, puis téléchargez le résultat. Augmentez le niveau de correction d’erreur pour qu’un code reste lisible lorsqu’il est imprimé en petit format ou partiellement masqué. La même boîte de dialogue permet également de choisir les couleurs et d’ajouter un logo.
Laissez-le fonctionner
Un service de raccourcissement peut échouer sans produire d’erreur visible. Les liens cessent de rediriger et personne ne vous prévient, car la personne qui a cliqué pense que le lien est simplement mort. Configurez le contrôle de disponibilité sur une URL courte réelle plutôt que sur la page d’accueil, et déclenchez une alerte pour toute réponse qui n’est pas une redirection. Une instance Uptime Kuma auto-hébergée convient bien à cet usage et peut surveiller un code d’état précis.
Sauvegardez la base de données, pas le conteneur. Une commande suffit pour l’exporter.
sudo docker compose exec -T database pg_dump -U shlink shlink | gzip > shlink-$(date +%F).sql.gzCe fichier, votre fichier compose et .env permettent de reconstruire l’ensemble du service sur un nouveau serveur. Chaque application du serveur doit disposer de sa propre version de cette sauvegarde. Une photothèque est un cas particulier, car PhotoPrism et Immich stockent les originaux sur disque ainsi que des enregistrements dans une base de données. Un simple dump restaure donc les enregistrements de la base, mais pas une seule photo ni les paramètres de PhotoPrism stockés dans des fichiers. Sauvegardez également la configuration de PhotoPrism, notamment le fichier settings.yml qui contient les préférences d’interface, de téléchargement et d’indexation. Les mises à niveau sont sudo docker compose pull suivies de sudo docker compose up -d, et Shlink exécute toutes les nouvelles migrations au démarrage. Effectuez le dump avant le pull, car une migration ne peut pas être annulée.
FAQ
Pourquoi mes liens courts renvoient-ils une erreur 404 après l’ajout d’un reverse proxy ?
Shlink compare un code court au domaine indiqué dans l’en-tête Host. Si le proxy envoie un autre host, Shlink vérifie ce domaine, puis recherche un lien correspondant dans le domaine par défaut. Il renvoie une erreur 404 si aucun des deux domaines ne contient ce code. Définissez proxy_set_header Host $host; dans le bloc location de nginx, puis rechargez le proxy. Les liens fonctionnent immédiatement, sans redémarrer le conteneur.
Ai-je besoin de Postgres ou SQLite suffit-il ?
SQLite convient pour tester Shlink et ne nécessite pas de second conteneur. Passez à Postgres avant de publier des liens importants, car le nombre de lignes de visites augmente à chaque clic et SQLite sérialise les écritures. Une migration ultérieure nécessite d’exporter puis de réimporter vos liens. Choisir Postgres dès le départ vous évite donc cette migration.
Puis-je récupérer une clé API que j’ai oublié de copier ?
Non. Shlink stocke un hash de la clé. api-key:list affiche donc les noms et l’état, mais jamais la valeur. Générez une clé de remplacement avec shlink api-key:generate, collez-la dans le client web, puis désactivez l’ancienne avec shlink api-key:disable pour qu’elle cesse de fonctionner.
Pourquoi les colonnes de pays sont-elles vides dans mes statistiques de visites ?
La géolocalisation nécessite la base de données GeoLite2. Shlink la télécharge uniquement si vous lui fournissez un GEOLITE_LICENSE_KEY. La clé est gratuite auprès de MaxMind. Ajoutez-la à la section d’environnement, recréez le conteneur, puis les nouvelles visites seront géolocalisées. Les visites enregistrées auparavant restent vides jusqu’à l’exécution de shlink visit:locate.
Comment déplacer Shlink vers un autre serveur ?
Conservez le domaine et déplacez les données. Exportez la base de données avec pg_dump, puis copiez le dump, le fichier compose et .env sur le nouveau serveur. Démarrez uniquement la base de données, restaurez le dump dans la base vide, puis démarrez Shlink et le client web avant l’arrivée du trafic réel. Modifiez l’enregistrement DNS en dernier. Les codes courts et leur historique de visites sont conservés, car toutes les données résident dans la base de données.