SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor · Aggiornato 2026-11-20

Accorciatore URL self-hosted con Shlink e Docker

Configura Shlink 5.1 su un VPS con Docker Compose: dominio breve, DNS, Postgres, chiavi API, client web, codici QR e statistiche sui clic.

Cosa stai configurando

Un accorciatore di URL self-hosted è un piccolo server che trasforma un link lungo in uno breve di tua proprietà e registra ogni clic. Shlink è la scelta adatta: è open source, viene distribuito come immagine Docker e svolge l’intero lavoro usando un container e un database. Questa guida lo installa su un VPS dietro un dominio breve dedicato, con HTTPS, una chiave API, codici QR e statistiche sui clic.

Sono due i componenti che offrono un’esperienza simile a quella di un accorciatore commerciale. Il server API gestisce i redirect e memorizza i dati. Il client web è un’applicazione statica separata che comunica con l’API dal browser. Puoi eseguire entrambi oppure usare solo l’API e controllarla dalla riga di comando.

I numeri di versione riportati sono quelli correnti al 19 novembre 2026: Shlink 5.1.8 e shlink-web-client 4.9.0.

Punta prima un dominio breve al server

Il dominio è il prodotto. s.example.com/abc123 è il collegamento che gli utenti vedono, quindi scegline uno breve e decidi quale usare prima di installare qualsiasi componente. Shlink associa ogni URL breve al dominio predefinito o a un dominio assegnato esplicitamente. Se lo cambi in seguito, devi continuare a puntare il vecchio dominio a Shlink, in modo che i collegamenti già distribuiti continuino a funzionare.

Crea un record DNS A per il dominio breve e fallo puntare all'indirizzo IPv4 pubblico del tuo VPS. Aggiungi anche un record AAAA se il server dispone di IPv6. Quindi verifica che il dominio venga risolto prima di continuare.

dig +short s.example.com A

L'output deve essere l'indirizzo del server. Se è vuoto, il record non è ancora stato propagato. Tutti i passaggi successivi falliranno in modo poco chiaro, perché non è possibile emettere un certificato TLS (transport layer security) per un nome che non viene risolto.

Il file compose

Shlink richiede un database. SQLite è sufficiente per un test, ma Postgres è la scelta corretta per qualsiasi installazione che si prevede di conservare, perché le righe relative alle visite aumentano nel tempo e Postgres gestisce meglio gli indici e le scritture concorrenti. Inserisci questo contenuto 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:

Entrambe le porte pubblicate sono associate a 127.0.0.1, quindi nulla è raggiungibile da Internet finché non viene configurato il reverse proxy nella sezione successiva. Docker applica le proprie regole di inoltro prima del firewall dell'host. Di conseguenza, una semplice regola 8080:8080 esporrebbe l'applicazione anche su un sistema il cui firewall sembra chiuso. L'associazione all'indirizzo di loopback evita questo problema. Lo stesso schema si applica a qualsiasi applicazione eseguita in questo modo ed è descritto più dettagliatamente nella guida a Docker Compose su un VPS.

La password del database proviene da un file .env accanto al file compose, quindi non viene inserita nello 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/.env

Avvialo e monitora l'avvio dell'API.

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

Al primo avvio vengono eseguite le migrazioni del database, quindi l'operazione richiede più tempo rispetto agli avvii successivi. Quando il servizio è avviato, verifica che risponda localmente.

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

Un valore 200 indica che l'API è attiva e che la connessione al database funziona. Un valore 503 indica che Shlink è in esecuzione, ma il controllo del database non è riuscito. L'endpoint di health restituisce 503 per qualsiasi errore del database, mai 500. Se curl stampa invece 000, non ha ricevuto alcun codice di risposta HTTP. Prima di concludere che il container si sia arrestato o sia in fase di riavvio, verifica la connettività e i log riportati sopra. Se nei log compare un errore di autenticazione al database, verifica che DB_PASSWORD in .env corrisponda al valore usato per creare il database, perché l'immagine Postgres legge POSTGRES_PASSWORD solo quando inizializza una directory dati vuota. Modificare successivamente .env non cambia la password esistente del database. Devi modificare anche la password del ruolo del database oppure ripristinare la password esistente in .env.

Termina HTTPS davanti al servizio

Shlink fornisce HTTP non cifrato sulla porta 8080. TLS deve essere gestito da un reverse proxy. L’impostazione importante consiste nel trasmettere il nome host originale. Shlink usa l’header Host per cercare gli short code, con un fallback alla ricerca dei link corrispondenti sul dominio predefinito. Un host riscritto può quindi selezionare il link errato oppure restituire 404 per un codice che esiste solo su un altro dominio.

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;
    }
}

Quindi emetti il certificato. La procedura completa, incluso il timer per il rinnovo, è disponibile nella guida a Certbot per nginx su Ubuntu 24.04.

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

Nel file compose, IS_HTTPS_ENABLED: "true" fa sì che Shlink inserisca https:// negli short URL restituiti. Non abilita TLS autonomamente. Lascialo false dietro un proxy HTTPS: ogni link restituito dall’API sarà un link http:// che esegue quindi un redirect, causando un round trip aggiuntivo e un risultato anomalo nel client web.

Crea una chiave API

L’API di gestione richiede una chiave; l’endpoint di health check è pubblico. Generane una tramite la CLI all’interno del container.

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

Il comando stampa la chiave una sola volta. Copiala subito, perché viene memorizzata sotto forma di hash e non può essere visualizzata nuovamente. shlink api-key:list mostra i nomi e indica se ogni chiave è abilitata, ma non mostra mai la chiave. Revoca una chiave con shlink api-key:disable e il relativo nome.

Invia la chiave in un’intestazione X-Api-Key per le chiamate REST di gestione.

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

Un oggetto JSON con una chiave shortUrls indica che la chiave funziona. Un 401 il cui type è https://shlink.io/api/error/invalid-api-key, con titolo Invalid API key, indica che la chiave è errata, disabilitata o scaduta.

La CLI è il metodo più rapido per creare link ed è adatta all'automazione tramite script.

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 restituisce un link leggibile invece di un codice generato. Gli slug sono univoci per dominio, quindi un secondo tentativo di usare uno slug già occupato non riesce e non sovrascrive il primo link. --tag può essere ripetuto; i tag servono a raggruppare i link per i quali si vorranno ottenere statistiche aggregate in seguito.

Elenca ciò che esiste, quindi controlla il traffico di un link.

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

short-url:visits stampa una riga per ogni clic, con data, referrer e user agent. Le colonne relative a paese e città restano vuote se non imposti una variabile d'ambiente GEOLITE_LICENSE_KEY, che corrisponde a una chiave MaxMind gratuita usata da Shlink per scaricare il database GeoLite2. Senza questa variabile, le visite vengono comunque registrate, ma non ne viene determinata la posizione.

Il client web e i codici QR

Il client web è ora disponibile all’indirizzo 127.0.0.1:8081 e richiede una propria configurazione proxy, oppure un tunnel SSH se si preferisce non pubblicarlo. Al primo caricamento richiede l’URL del server e una chiave API. Inserire https://s.example.com e la chiave generata. Il client conserva entrambi i valori nello storage del browser e chiama direttamente l’API, quindi nessun dato passa attraverso terzi. Separare l’interfaccia dall’API è un modello architetturale utile da considerare, perché è lo stesso che consente a Halcyon di presentare una libreria Jellyfin come un videonoleggio degli anni 1990 senza modificare il media server sottostante.

I codici QR vengono generati dal client web, non dall’API. Shlink 5 ha rimosso il vecchio metodo che consisteva nell’aggiungere /qr-code a un URL abbreviato, quindi quell’indirizzo non restituisce più un’immagine. Il client web genera invece il codice nel browser, senza inviare richieste a Shlink. Aprire l’opzione del codice QR su un link nell’elenco degli URL abbreviati, impostare dimensioni, formato e margine, quindi scaricare il risultato. Aumentare il livello di correzione degli errori per ottenere un codice che continui a essere leggibile anche se stampato in piccolo o parzialmente coperto. La stessa finestra di dialogo consente di impostare anche i colori e un logo.

Mantienilo in esecuzione

Un servizio di abbreviazione può smettere di funzionare senza segnalazioni. I link non reindirizzano più e nessuno lo comunica, perché chi fa clic presume che il link non sia più valido. Configura un controllo di uptime su un URL breve reale, non sulla home page, e genera un avviso per qualsiasi risposta che non sia un redirect. Un'istanza self-hosted di Uptime Kuma è adatta a questo scopo e può verificare uno specifico codice di stato.

Esegui il backup del database, non del container. Un comando crea il dump.

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

Questo file, insieme al file compose e a .env, ricrea l'intero servizio su un nuovo server. Ogni applicazione sul server deve avere una propria versione di questo backup. Una libreria fotografica è il caso più complesso, perché PhotoPrism e Immich conservano gli originali su disco oltre alle righe nel database. Un dump ripristina quindi i record del database, ma non una singola foto né le impostazioni basate su file di PhotoPrism. Esegui il backup anche della configurazione di PhotoPrism, incluso il file settings.yml che contiene le preferenze dell'interfaccia utente, dei download e dell'indicizzazione. Gli aggiornamenti vengono eseguiti con sudo docker compose pull, seguiti da sudo docker compose up -d, e Shlink applica le nuove migrazioni all'avvio. Crea il dump prima di eseguire il pull, perché una migrazione non può essere annullata.

FAQ

Shlink confronta il codice breve con il dominio nell'header Host. Se il proxy invia un host diverso, Shlink verifica quel dominio e poi cerca un link con dominio predefinito corrispondente; restituisce 404 se il codice non viene trovato in nessuno dei due. Imposta proxy_set_header Host $host; nel blocco location di nginx e ricarica il proxy. I link iniziano a funzionare subito, senza riavviare il container.

Ho bisogno di Postgres o è sufficiente SQLite?

SQLite è adatto per provare Shlink e non richiede un secondo container. Passa a Postgres prima di pubblicare link importanti, perché il numero di righe delle visite cresce a ogni clic e SQLite serializza le scritture. Una migrazione successiva richiede l'esportazione e la reimportazione dei link, quindi scegliere Postgres all'inizio evita questa operazione.

Posso recuperare una chiave API che ho dimenticato di copiare?

No. Shlink memorizza un hash della chiave, quindi api-key:list mostra i nomi e lo stato, ma non il valore. Genera una sostituzione con shlink api-key:generate, incollala nel client web, quindi disabilita la chiave precedente con shlink api-key:disable per impedirne l'uso.

Perché le colonne dei paesi sono vuote nelle statistiche delle visite?

La geolocalizzazione richiede il database GeoLite2, che Shlink scarica solo quando fornisci un GEOLITE_LICENSE_KEY. La chiave è gratuita ed è disponibile presso MaxMind. Aggiungila alla sezione dell'ambiente, ricrea il container e le nuove visite verranno geolocalizzate. Le visite registrate in precedenza resteranno senza dati finché non esegui shlink visit:locate.

Mantieni il dominio e sposta i dati. Esegui il dump del database con pg_dump, copia il dump, il file compose e .env sul nuovo server, avvia solo il database, ripristina il dump nel database vuoto, quindi avvia Shlink e il client web prima che arrivi traffico reale. Modifica per ultima la voce DNS. I codici brevi e la cronologia delle visite vengono mantenuti, perché tutti i dati risiedono nel database.

Questo articolo ti è stato utile?

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