Come fare self-hosting di Shlink nel 2026: domini, API key e statistiche

Il self-hosting di Shlink diventa interessante al primo redeploy, non al primo docker run. Se i link generati usano HTTP o le migration non riescono a raggiungere il database, Docker può comunque segnalare un processo perfettamente operativo. Il deployment seguente è organizzato intorno a comportamenti osservabili: creare uno short URL tramite l'API, seguirne il redirect, registrare le visite e consultare le statistiche dal client web.

Il compito di Shlink è chiaro: un link shortener API-first con statistiche. Questa descrizione indica cosa deve restare pubblico, cosa dovrebbe rimanere privato e cosa deve essere ricostruito da un backup.

Da cosa dipende Shlink

Per Shlink, lo stato del processo e quello del prodotto sono due cose separate. La porta 8080 può rispondere mentre la transazione esposta agli utenti continua a fallire. Il contratto di rete di Shlink richiede Postgres o MariaDB, oltre a Redis opzionale per la produzione. Mantieni gli endpoint privati su DNS interno, consenti solo le chiamate in uscita necessarie e assegna a Shlink una credenziale di servizio con autorizzazioni limitate.

Esegui questa verifica di readiness dopo modifiche significative alla configurazione: crea uno short URL tramite l'API, seguine il redirect, registra le visite e consulta le statistiche dal client web. Tieni i controlli esterni costosi fuori dai probe di liveness, così un'interruzione di un provider non causa un restart loop. Il lavoro sulla capacità dovrebbe monitorare il throughput dei redirect, le scritture sul database, i download di geolocalizzazione e il comportamento della cache: aspetti più vicini alla pressione reale su Shlink rispetto alle richieste delle pagine.

I volumi sono solo il primo livello di ripristino

L'immagine standard di Shlink non prevede uno stato applicativo scrivibile al suo interno. Conserva il database, le API key e gli eventuali dati delle visite importati, incluso il digest fissato e la configurazione delle route verificata, invece di eseguire il backup di un filesystem vuoto del container.

Crea Shlink da zero su un altro host e verifica che domini, short code, tag e record delle visite vengano ripristinati e che ogni short URL campionato esegua lo stesso redirect. Se aggiungi un database separato, un room server o un livello di autenticazione, assegna a ciascun componente un responsabile esplicito per il ripristino. La guida da Git alla produzione mostra come un artefatto riproducibile sostituisca il backup di un container.

Registra il comando di ricostruzione e il test con output noto insieme alla release. Un piano di ripristino stateless ha successo quando riproduce il comportamento a partire da input attendibili; non dovrebbe dipendere dalla copia di un container in esecuzione e non trasparente.

Proteggi la parte più importante di Shlink

Un deployment sicuro di Shlink inizia rimuovendo le autorizzazioni superflue. Evita di esporre la chiave API REST o di cambiare il dominio pubblico dopo la pubblicazione dei link; mantieni invece le API key fuori dal codice del browser, usa HTTPS e limita l'amministrazione lasciando pubblici i redirect.

DEFAULT_DOMAIN è una configurazione, non un segreto: mantienine esplicito il valore, proteggendo al contempo le credenziali separate usate da Shlink. Limita le route amministrative, usa DNS privato per le dipendenze e verifica ogni bind mount. Quando i log vengono inviati a un sistema centralizzato, filtra segreti e contenuti privati prima che lascino il server.

Trasforma lo smoke test di Shlink in un controllo della release

Per Shlink, definisci una transazione valida prima del lancio: crea uno short URL tramite l'API, seguine il redirect, registra le visite e consulta le statistiche dal client web. Inserisci in un sistema di version control i prerequisiti, la risposta attesa e i passaggi di cleanup, senza valori segreti. Fissa l'immagine usata per stabilire questo riferimento.

Usa la transazione per convalidare un'istanza sostitutiva e un ripristino indipendente. Il servizio ripristinato è accettabile solo quando domini, short code, tag e record delle visite vengono recuperati e ogni short URL campionato esegue lo stesso redirect. Allo stesso tempo, osserva il throughput dei redirect, le scritture sul database, i download di geolocalizzazione e il comportamento della cache, quindi trasforma la parte più lenta o più vincolata in un alert a livello di servizio.

Il gate deve includere anche un caso negativo: nega temporaneamente all'identità di test l'accesso a Postgres o MariaDB, oltre a Redis opzionale per la produzione. Verifica che Shlink produca un errore utile senza compromettere i dati, ripristina la condizione valida e ripeti la transazione corretta. Conservare entrambi i risultati impedisce che un endpoint di health superficiale diventi l'unica prova disponibile in produzione.

Avvia Shlink senza nascondere le parti mobili

Il comando seguente rende visibile il confine del container senza fingere di predisporre ogni servizio esterno.

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

Prima di aprire l'ingress, controlla l'ambiente risolto, i mount e il listener. Aggiungi le impostazioni di connessione verificate per Postgres o MariaDB, oltre a Redis opzionale per la produzione; usa nomi privati per i servizi privati. Un avvio riuscito si conclude quando puoi creare uno short URL tramite l'API, seguirne il redirect, registrare le visite e consultare le statistiche dal client web, non quando docker ps stampa Up.

Assegna a Shlink un unico indirizzo canonico

Il confine pubblico di Shlink dovrebbe essere costituito da un unico hostname canonico, TLS automatico e un unico target interno sulla porta 8080. Imposta DEFAULT_DOMAIN e IS_HTTPS_ENABLED prima di creare short URL, così i client torneranno a un indirizzo riconosciuto dal servizio.

Se la transazione di accettazione fallisce, classifica il primo errore. I problemi relativi a DNS, certificati e 502 rientrano nella checklist di validazione TLS. La condizione «i link generati usano HTTP o le migration non riescono a raggiungere il database» riguarda il lato applicativo, dopo che una richiesta ha raggiunto correttamente Shlink.

Diagnostica di un Shlink apparentemente operativo

Per Shlink, monitora una transazione anziché un processo: crea uno short URL tramite l'API, seguine il redirect, registra le visite e consulta le statistiche dal client web. Combina latenza e tasso di errore con il throughput dei redirect, le scritture sul database, i download di geolocalizzazione e il comportamento della cache, così un alert identificherà il componente sotto maggiore pressione.

La prova generale dell'upgrade deve coprire il fatto che le migration del database e la compatibilità delle API vadano gestite per fasi, perché gli short link pubblicati non possono aspettare una correzione manuale. Esegui il ripristino, le migration e la transazione prima della sostituzione in produzione. Se i link generati usano HTTP o le migration non riescono a raggiungere il database, non cancellare i dati per far risultare positivo l'avvio; confronta in quest'ordine versione, variabili, mount e raggiungibilità delle dipendenze.

Mantieni Shlink esplicito mentre Dockup gestisce il routing

Il deployment one-click di Shlink su Dockup dovrebbe rendere sicura la sostituzione: la route continua a puntare alla porta 8080, i segreti non vengono incorporati nell'immagine e i percorsi persistenti vengono ripristinati nel nuovo container. Lo stesso deployment può essere eseguito sul compute di Dockup o su una macchina collegata.

Completa il lavoro specifico dell'app collegando e testando Postgres o MariaDB, oltre a Redis opzionale per la produzione, applicando l'indirizzo pubblico canonico ed eseguendo questo controllo di accettazione: crea uno short URL tramite l'API, seguine il redirect, registra le visite e consulta le statistiche dal client web. Aggiungi il risultato del ripristino al runbook prima che arrivino gli utenti reali.

Domande frequenti

Di cosa ha bisogno Shlink per un deployment in produzione?

Instrada il container Shlink sulla porta 8080 attraverso un'unica origine HTTPS. Il requisito di rete di supporto è Postgres o MariaDB, oltre a Redis opzionale per la produzione. Non considerare Shlink pronto finché non puoi creare uno short URL tramite l'API, seguirne il redirect, registrare le visite e consultare le statistiche dal client web.

Quali dati di Shlink devono essere inclusi in un backup?

L'immagine standard di Shlink non dispone di un mount obbligatorio per i dati applicativi. Conserva la configurazione del deployment ed esegui separatamente il backup di qualsiasi stato collegato; il ripristino è riuscito quando domini, short code, tag e record delle visite vengono recuperati e ogni short URL campionato esegue lo stesso redirect.

Shlink richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Shlink e mantieni la porta 8080 nella route interna. Applica correttamente l'impostazione di Shlink: imposta DEFAULT_DOMAIN e IS_HTTPS_ENABLED prima di creare short URL. Per Shlink, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento dei client sensibile all'origine.

Come va testato un upgrade di Shlink?

Ripristina lo stato corrente di Shlink in un deployment isolato, applica la versione candidata e ripeti la relativa transazione di accettazione. Presta particolare attenzione al fatto che le migration del database e la compatibilità delle API vadano gestite per fasi, perché gli short link pubblicati non possono aspettare una correzione manuale. Conserva l'immagine precedente di Shlink finché non sono chiari i limiti della migrazione dei dati e del rollback.