Pourquoi héberger votre propre raccourcisseur d'URL
Un raccourcisseur public décide à votre place : il peut changer ses conditions, limiter le nombre de liens, afficher une page intermédiaire ou disparaître, et vos liens déjà imprimés cessent alors de fonctionner. Ses statistiques lui appartiennent, et son domaine partagé est régulièrement bloqué par les filtres anti-hameçonnage parce que d'autres l'utilisent mal.
Avec Kutt sur votre VPS, le lien go.votre-domaine.ma/offre est à vous pour toujours : vous pouvez changer sa destination sans réimprimer l'affiche, consulter qui a cliqué et d'où, et aucun tiers ne voit vos campagnes. Pour une agence, c'est aussi un service à proposer à chaque client, sur son propre domaine.
Ce que Kutt apporte
- Liens à votre domaine — chaque lien court porte votre marque et reste valide même si vous changez d'outil plus tard.
- Adresses personnalisées —
/rentree,/webinar, ou un code de six caractères généré sans caractères ambigus. - Mot de passe et expiration — un lien protégé pour un document client, un lien qui cesse de rediriger à la fin d'une offre.
- Statistiques privées — visites dans le temps, navigateurs, systèmes, pays et sites référents, visibles du seul propriétaire.
- API REST — une clé par utilisateur pour créer, modifier et supprimer des liens depuis vos scripts et vos outils.
- Administration — création des comptes de l'équipe, revue de tous les liens, bannissement d'un lien ou d'un domaine abusif.
Kutt, Shlink et un service public
Faites défiler le tableau
| Kutt | Shlink | Service public (bit.ly…) | |
|---|---|---|---|
| Interface web | Intégrée | Client web séparé | Oui |
| API REST | Oui, clé par utilisateur | Oui, clés gérées en ligne de commande | Oui, souvent payante |
| Votre propre domaine | Oui, inclus | Oui, inclus | Option payante |
| Statistiques | Dans votre base | Dans votre base | Chez le fournisseur |
| Comptes d'équipe | Oui, créés par l'administrateur | Non, accès par clé d'API | Selon l'offre |
| Stockage | SQLite, PostgreSQL ou MySQL | SQLite, PostgreSQL, MySQL ou SQL Server | Géré par le fournisseur |
Prérequis
Un VPS Ubuntu 24.04 avec 512 Mo de RAM et 5 Go de disque suffit : Kutt tourne dans un seul conteneur Node.js et utilise environ 200 Mo de mémoire. Il vous faut Docker avec le plugin Compose, nginx et certbot pour le HTTPS, et un nom DNS qui pointe vers le VPS.
Choisissez ce nom avec soin, car il forme chaque lien : plus il est court, plus vos liens le sont. Un sous-domaine comme go.votre-domaine.ma ou un petit domaine dédié fonctionne très bien. Kutt l'inscrit dans chaque lien créé, si bien que le changer plus tard ne réécrit pas les liens déjà partagés.
Installer Kutt avec Docker Compose
Préparer le répertoire et les secrets
Créez le répertoire de l'application et un fichier
.envqui porte la clé secrète (elle signe les sessions) et le domaine des liens courts. Remplacezgo.example.compar votre propre nom.mkdir -p /opt/kutt && cd /opt/kutt printf 'SECRET_KEY=%s\nDOMAIN=go.example.com\n' "$(openssl rand -hex 32)" > .env chmod 600 .envÉcrire le fichier compose
Créez
compose.yaml. Le port n'est publié que sur la boucle locale : seul nginx y accède. Les inscriptions publiques et les liens anonymes restent fermés, et la base SQLite vit dans un volume nommé.services: kutt: image: kutt/kutt:v3.2.6 restart: unless-stopped ports: - "127.0.0.1:8107:3000" environment: JWT_SECRET: ${SECRET_KEY:?SECRET_KEY requis} DEFAULT_DOMAIN: ${DOMAIN:?DOMAIN requis} DB_CLIENT: better-sqlite3 DB_FILENAME: /var/lib/kutt/data.sqlite TRUST_PROXY: "true" DISALLOW_REGISTRATION: "true" DISALLOW_ANONYMOUS_LINKS: "true" volumes: - kutt-data:/var/lib/kutt - kutt-custom:/kutt/custom volumes: kutt-data: {} kutt-custom: {}Démarrer et vérifier
Lancez la pile. Kutt applique ses migrations au démarrage, puis la sonde de santé doit répondre 200.
docker compose up -d docker compose ps curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8107/api/v2/healthPublier Kutt en HTTPS
Déclarez un hôte virtuel nginx qui transmet les requêtes au port local, puis demandez le certificat avec certbot. L'en-tête
X-Forwarded-Forpermet à Kutt de compter la vraie adresse des visiteurs (TRUST_PROXY).server { server_name go.example.com; location / { proxy_pass http://127.0.0.1:8107; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }certbot --nginx -d go.example.com
Créez le compte administrateur sans attendre
Kutt ne crée aucun compte à l'avance : tant qu'aucun utilisateur n'existe, la page d'accueil redirige vers le formulaire create admin, et le premier visiteur devient administrateur. Ouvrez votre domaine dès que le HTTPS fonctionne et créez votre compte avec un mot de passe solide. Ensuite le formulaire refuse toute nouvelle création.
Créer des liens par l'API
Dans les paramètres de votre compte, générez une clé d'API, puis envoyez-la dans l'en-tête X-API-KEY. Le corps JSON accepte target (l'adresse longue) et, en option, customurl, password, description et expire_in (une durée comme 7 days).
curl -s -X POST https://go.example.com/api/v2/links \
-H "X-API-KEY: $KUTT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"target": "https://example.com/une/adresse/tres/longue", "customurl": "promo", "expire_in": "7 days"}'La réponse contient le champ link, le lien court complet. Le même point d'accès en GET liste vos liens avec leur nombre de visites, et /api/v2/links/<id>/stats rend les statistiques détaillées d'un lien. C'est ce qui permet de brancher Kutt sur un CRM, un script de facturation ou une campagne d'e-mailing : chaque lien sortant est raccourci et mesuré sans intervention.
Travailler en équipe
Les inscriptions sont fermées : c'est l'administrateur qui crée les comptes depuis la page d'administration. Chaque membre a ses propres liens, ses statistiques privées et sa clé d'API, révocable en la régénérant. L'administrateur voit tous les liens de l'instance et peut bannir un lien abusif ; c'est important, car un raccourcisseur au nom de votre domaine engage sa réputation.
Kutt accepte aussi des domaines supplémentaires, ajoutés dans les paramètres. Chacun doit pointer vers le VPS et disposer de son propre certificat : commencez avec un seul domaine, puis ajoutez les autres un par un.
Activer les e-mails
Kutt s'installe avec les e-mails désactivés : pas de réinitialisation de mot de passe par e-mail ni de vérification d'adresse. Pour les activer, ajoutez dans l'environnement du conteneur MAIL_ENABLED: "true" et les variables MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASSWORD et MAIL_FROM de votre serveur SMTP, puis relancez avec docker compose up -d. Gardez une note du mot de passe administrateur en attendant : sans e-mail, sa perte se règle en base.
Dimensionner le VPS
Pour une équipe et quelques milliers de liens, 512 Mo de RAM et un vCPU suffisent largement : la redirection est une simple lecture en base. La base SQLite grossit avec les visites enregistrées, de l'ordre de quelques centaines d'octets par clic. Au-delà de centaines de milliers de clics par jour, passez à PostgreSQL (DB_CLIENT: pg) et activez Redis (REDIS_ENABLED) pour le cache.
Sauvegarde et mise à jour
Toute la donnée tient dans le volume kutt-data : la base SQLite contient les comptes, les liens et les statistiques. Arrêtez le conteneur un instant pour obtenir une copie cohérente, puis archivez le volume.
docker compose stop kutt
docker run --rm -v kutt_kutt-data:/data -v "$PWD":/backup alpine \
tar czf /backup/kutt-$(date +%F).tar.gz -C /data .
docker compose start kuttPour mettre à jour, lisez les notes de version du projet, changez l'étiquette de l'image, puis tirez la nouvelle image : les migrations s'appliquent au démarrage. Faites toujours une sauvegarde juste avant.
# changer l'étiquette de l'image dans compose.yaml, puis :
docker compose pull && docker compose up -dInstallation en un clic depuis le Marketplace ServOrbit
Sur un VPS ServOrbit, Kutt s'installe depuis le Marketplace de votre espace client : choisissez l'adresse — un sous-domaine court de l'un de vos domaines ou le sous-domaine gratuit du VPS, HTTPS compris — et cliquez sur Installer. Le script déploie le conteneur, génère la clé secrète, règle le domaine des liens et configure nginx. Il ne vous reste qu'à ouvrir votre domaine pour créer le compte administrateur, puis votre première clé d'API.
