Comment auto-héberger Shlink en 2026 : domaines, clés API et statistiques

L’auto-hébergement de Shlink devient intéressant lors du premier redeploy, pas du premier docker run. Si les liens générés utilisent HTTP ou si les migrations ne peuvent pas atteindre la base de données, Docker peut tout de même signaler un processus parfaitement sain. Le déploiement ci-dessous est organisé autour de comportements observables : créer une URL courte via l’API, suivre sa redirection, enregistrer les visites et consulter les statistiques depuis le client web.

Le rôle de Shlink est clairement défini : un raccourcisseur de liens API-first avec statistiques. Cette description indique ce qui doit rester public, ce qui doit rester privé et ce qu’une sauvegarde doit pouvoir reconstruire.

Les dépendances de Shlink

La santé du processus et celle du produit sont deux choses distinctes pour Shlink. Le port 8080 peut répondre alors que la transaction côté utilisateur échoue toujours. Le contrat réseau de Shlink repose sur Postgres ou MariaDB, avec Redis en option pour la production. Gardez les endpoints privés sur un DNS interne, n’autorisez que les appels sortants nécessaires et attribuez à Shlink un identifiant de service aux permissions limitées.

Utilisez cet exercice de readiness après toute modification importante de la configuration : créez une URL courte via l’API, suivez sa redirection, enregistrez les visites et consultez les statistiques depuis le client web. Gardez les vérifications externes coûteuses en dehors des probes de liveness afin qu’une panne d’un fournisseur ne provoque pas une boucle de redémarrage. Le travail de capacity planning doit suivre le débit des redirections, les écritures en base de données, les téléchargements de données de géolocalisation et le comportement du cache, ce qui reflète mieux la charge réelle de Shlink que les requêtes de pages.

Les volumes ne constituent que le premier niveau de restauration

Aucun état applicatif accessible en écriture n’est attendu dans l’image Shlink standard. Préservez la base de données, les clés API et toutes les données de visites importées, y compris le digest épinglé et la configuration des routes vérifiée, plutôt que de sauvegarder un système de fichiers de conteneur vide.

Recréez Shlink depuis zéro sur un autre hôte et vérifiez que les domaines, les short codes, les tags et les enregistrements de visites sont restaurés, et que chaque URL courte échantillonnée redirige exactement de la même manière. Si une base de données distincte, un room server ou une couche d’authentification est ajouté, attribuez à ce composant un responsable explicite pour sa restauration. Le guide Git vers la production montre comment un artefact reproductible remplace une sauvegarde de conteneur.

Consignez la commande de reconstruction et le test au résultat connu avec la release. Un plan de restauration stateless réussit en reproduisant le comportement à partir d’entrées fiables ; il ne doit pas dépendre de la copie d’un conteneur en cours d’exécution et opaque.

Protégez la partie précieuse de Shlink

Un déploiement Shlink sécurisé commence par la suppression des privilèges inutiles. Évitez d’exposer la clé API REST ou de modifier le domaine public une fois les liens publiés ; gardez plutôt les clés API hors du code exécuté dans le navigateur, utilisez HTTPS et restreignez l’administration tout en laissant les redirections publiques.

DEFAULT_DOMAIN est un paramètre de configuration, pas un secret ; gardez sa valeur explicite tout en protégeant les identifiants distincts utilisés par Shlink. Restreignez les routes d’administration, utilisez un DNS privé pour les dépendances et vérifiez chaque bind mount. Lorsque les logs sont envoyés vers un système centralisé, filtrez les secrets et les contenus privés avant qu’ils ne quittent le serveur.

Transformez le smoke test de Shlink en contrôle de release

Pour Shlink, définissez une transaction de référence avant le lancement : créez une URL courte via l’API, suivez sa redirection, enregistrez les visites et consultez les statistiques depuis le client web. Placez ses prérequis, la réponse attendue et les étapes de nettoyage sous contrôle de version, sans valeurs secrètes. Épinglez l’image utilisée pour établir cette référence.

Utilisez cette transaction pour valider un remplacement et une restauration indépendante. Le service restauré n’est acceptable que lorsque les domaines, les short codes, les tags et les enregistrements de visites sont restaurés, et que chaque URL courte échantillonnée redirige exactement de la même manière. En parallèle, observez le débit des redirections, les écritures en base de données, les téléchargements de données de géolocalisation et le comportement du cache, puis transformez la partie la plus lente ou la plus contrainte en alerte de niveau de service.

Le contrôle doit également inclure un cas négatif : refusez temporairement à l’identité de test l’accès à Postgres ou MariaDB, avec Redis en option pour la production. Vérifiez que Shlink produit une erreur exploitable tout en préservant les données, rétablissez la condition valide, puis répétez la transaction de référence. Conserver les deux résultats évite qu’un endpoint de santé superficiel devienne la seule preuve disponible en production.

Démarrez Shlink sans masquer les éléments mobiles

La commande suivante rend visible la limite du conteneur sans prétendre provisionner tous les services externes.

docker run -d \
  --name shlink \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -e DEFAULT_DOMAIN=go.example.com \
  shlinkio/shlink:stable

Avant d’ouvrir l’ingress, inspectez l’environnement résolu, les montages et le listener. Ajoutez les paramètres de connexion vérifiés pour Postgres ou MariaDB, avec Redis en option pour la production ; utilisez des noms privés pour les services privés. Un lancement réussi ne se termine que lorsque vous pouvez créer une URL courte via l’API, suivre sa redirection, enregistrer les visites et consulter les statistiques depuis le client web, et non lorsque docker ps affiche Up.

Attribuez à Shlink une adresse canonique

La frontière publique de Shlink doit reposer sur un hostname canonique unique, un TLS automatique et une seule cible interne sur le port 8080. Définissez DEFAULT_DOMAIN et IS_HTTPS_ENABLED avant de créer des URLs courtes afin que les clients reviennent vers une adresse reconnue par le service.

Si la transaction d’acceptation échoue, catégorisez la première erreur. Les problèmes de DNS, de certificat et de 502 relèvent de la checklist de validation TLS. La condition « les liens générés utilisent HTTP ou les migrations ne peuvent pas atteindre la base de données » relève de la couche applicative, une fois qu’une requête a bien atteint Shlink.

Diagnostiquez un Shlink qui semble sain

Pour Shlink, surveillez une transaction plutôt qu’un processus : créez une URL courte via l’API, suivez sa redirection, enregistrez les visites et consultez les statistiques depuis le client web. Combinez sa latence et son taux d’erreur avec le débit des redirections, les écritures en base de données, les téléchargements de données de géolocalisation et le comportement du cache, afin qu’une alerte identifie le composant sous contrainte.

La répétition générale de la mise à niveau doit couvrir le fait que les migrations de base de données et la compatibilité de l’API doivent être mises en staging, car les short links publiés ne peuvent pas attendre une réparation manuelle. Restaurez, migrez et exécutez la transaction avant de remplacer le service en production. Si les liens générés utilisent HTTP ou si les migrations ne peuvent pas atteindre la base de données, n’effacez pas les données pour faire passer le démarrage au vert ; comparez dans cet ordre la version, les variables, les montages et l’accessibilité des dépendances.

Gardez Shlink explicite pendant que Dockup gère le routage

Le déploiement Shlink en un clic de Dockup doit rendre le remplacement sûr : la route continue de cibler le port 8080, les secrets ne sont pas intégrés à l’image et les chemins persistants sont restaurés dans le nouveau conteneur. Le même déploiement peut fonctionner sur le compute de Dockup ou sur une machine attachée.

Terminez le travail spécifique à l’application en connectant et en testant Postgres ou MariaDB, avec Redis en option pour la production, en appliquant l’adresse publique canonique et en exécutant ce contrôle d’acceptation : créez une URL courte via l’API, suivez sa redirection, enregistrez les visites et consultez les statistiques depuis le client web. Ajoutez le résultat de la restauration au runbook avant l’arrivée des vrais utilisateurs.

Foire aux questions

De quoi Shlink a-t-il besoin pour un déploiement en production ?

Acheminez le conteneur Shlink sur le port 8080 via une origine HTTPS unique. L’exigence réseau complémentaire est Postgres ou MariaDB, avec Redis en option pour la production. Ne considérez pas Shlink comme prêt tant que vous ne pouvez pas créer une URL courte via l’API, suivre sa redirection, enregistrer les visites et consulter les statistiques depuis le client web.

Quelles données de Shlink doivent figurer dans une sauvegarde ?

L’image Shlink standard ne possède aucun volume de données applicatives obligatoire. Préservez sa configuration de déploiement et sauvegardez séparément tout état connecté ; la restauration est réussie lorsque les domaines, les short codes, les tags et les enregistrements de visites sont restaurés, et que chaque URL courte échantillonnée redirige exactement de la même manière.

Shlink a-t-il besoin de HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origine publique de Shlink et gardez le port 8080 sur la route interne. Appliquez correctement le paramètre Shlink : définissez DEFAULT_DOMAIN et IS_HTTPS_ENABLED avant de créer des URLs courtes. Pour Shlink, HTTPS protège les identifiants ou les contenus utilisateur pendant leur transit et garantit un comportement cohérent des clients sensibles à l’origine.

Comment tester une mise à niveau de Shlink ?

Restaurez l’état actuel de Shlink dans un déploiement isolé, appliquez la version candidate et répétez sa transaction d’acceptation. Soyez particulièrement attentif au fait que les migrations de base de données et la compatibilité de l’API doivent être mises en staging, car les short links publiés ne peuvent pas attendre une réparation manuelle. Conservez l’image Shlink précédente jusqu’à ce que les limites de migration des données et de rollback soient comprises.