Era marzo di quest’anno. Uno di quei tentativi da dopocena, con i bambini messi a nanna e la possibilità di svaccarsi (termine tecnico eh, mica pizza e fichi) sul divano a guardare qualcosa di decente in TV con mia moglie, quando mi sono messo in testa di provare DockFlare. Me lo aveva consigliato qualcuno (non ricordo più se su Reddit o nel solito gruppo di compari e nerd con cui chiacchiero ogni giorno) e l’idea di gestire i tunnel di Cloudflare direttamente a partire dai container Docker mi solleticava parecchio. Ormai sono passati tre anni e più da quando ho iniziato a tenere diverse cose in self-hosting tra le mura di casa (e su qualche servizio sparso online), quindi provo sempre cose nuove per migliorare l’esperienza d’uso dei prodotti sui quali mi appoggio nel quotidiano.

Sarà stata la stanchezza, sarà che quella sera ero semplicemente poco lucido, fatto sta che ho tirato in piedi un tunnel di test con cui giocare e rompere cose in santa pace.
Peccato che poi, volendo sperimentare sul serio, ho dato a DockFlare la conferma per prendere possesso del tunnel principale, quello che tiene in piedi buona parte dei servizi di casa. Quello che non avevo capito è che nell’intervallo di tempo tra il mio clic e l’esecuzione dell’operazione avrei perso tutte le configurazioni, dalla prima all’ultima, nessuna route sopravvissuta, vuoto pneumatico.

Sia chiaro: non è colpa di DockFlare, la conferma l’ho data io e la distrazione era tutta mia. Però intanto ho buttato giù il monitor del Mac, ho imprecato quanto serviva e ho rimandato tutto al giorno dopo. Ricostruire era fattibile, ma significava buttare via un mucchio di tempo. Quando l’ho fatto, ho anche provato a salvarmi la configurazione da qualche parte, un export da poter reimportare velocemente in caso di nuovo disastro, e non ho trovato niente che facesse al caso mio.

Il nome

In quella chat che alimentiamo a pane, cazzate e lamentele ogni giorno si stava parlando di India, di supporto, di call center e di non ricordo neanche più cos’altro. E a me era pure venuta fame senza apparente motivo. È in quel contesto, mentre con l’aiuto di Claude Code mettevo in piedi le prime righe di questo progetto, che ho scelto un nome provvisorio: Tikka Masala. Mi fa sorridere ancora oggi, il provvisorio è diventato definitivo, e il software esiste per rimediare a una mia disattenzione: ne ho avuto bisogno in prima persona e l’ho reso pubblico nella speranza che eviti ad altri la stessa situazione (o per lo meno l’idea è quella di provarci, stile raccomandazione della nonna su cosa devi fare per non prendere freddo).

Cosa fa

Il sottotitolo che ho scelto per il progetto è “backup and restore Cloudflare Tunnels, without the spreadsheet”, e riassume abbastanza bene le intenzioni.

Gli dai un API token di Cloudflare, lui verifica che sia valido, ti elenca i tunnel che vede sull’account e ti permette di salvarne uno snapshot: un file JSON con la configurazione del tunnel così come la restituiscono gli endpoint di configurazione dei Cloudflare Tunnel (regole di ingress, hostname pubblici), più i metadati che servono a ritrovarla (data dell’export, account, ID e nome del tunnel, eventuali note). I metadati e lo storico stanno in un piccolo database SQLite, gli snapshot veri e propri sono file su disco.

Il perimetro è quello e solo quello: la configurazione dei tunnel. Non tocca le impostazioni Cloudflare a livello di account, e non salva – al momento – Access (Applications e Policies), per cui trovi solo delle scorciatoie che ti portano dritto alla sezione giusta della dashboard. Quando serve, gli chiedi di ripristinare: prende lo snapshot e sovrascrive la configurazione remota del tunnel con quella salvata. Puoi rimetterla sul tunnel di origine, su un altro tunnel o su un altro account, e ogni ripristino resta tracciato nello storico (quando, su quale account, su quale tunnel).

I backup li fai partire a mano oppure li lasci a uno scheduler interno (con cron e possibilità di scegliere il fuso orario). Qui la parte che uso di più: per ogni tunnel scegli una frequenza, a ogni esecuzione, una volta a settimana o una volta al mese, e decidi se coprirli tutti o solo un sottoinsieme. Nel mio caso i tunnel che tocco spesso girano a ogni ciclo, quelli fermi da mesi si accontentano del giro mensile. C’è una retention (BACKUP_RETENTION_DAYS, io la tengo a 90 giorni) che dopo ogni nuovo backup fa piazza pulita di quelli più vecchi della soglia, snapshot e relativo storico compresi.

Occhio a una cosa sui permessi del token: per far girare anche i ripristini, Tikka Masala avrà necessità del permesso Cloudflare Tunnel in scrittura (più DNS sulla zona), ma se ti interessa solo il backup puoi tenerlo al guinzaglio e sola lettura. Il token viene cifrato, non resta in chiaro sul disco.

Sotto il cofano è un’applicazione FastAPI in Python, niente di esotico, con un sistema di notifiche via webhook o Telegram per farti sapere quando un backup o un ripristino va storto. L’ho rilasciato pronto per Docker (immagine gfsolone/tikkamasala su Docker Hub o in alternativa ghcr.io/gioxx/tikkamasala via GitHub, con un docker-compose di esempio disponibile sul repository): lo metti in piedi accanto agli altri servizi di casa, lo configuri la prima volta e te ne dimentichi (sempre però rispettando la regola che uno strumento di backup è definibile funzionante solo quando sei in grado di ripristinare senza il minimo errore, quindi provalo prima di metterti comodo sul tuo cuscino).

I numeri, i miei

Lo uso da marzo, senza interruzioni, e nel frattempo siamo arrivati alla versione 1.3.8.
A oggi che scrivo queste righe la mia installazione personale mi restituisce questa situazione:

Unique tunnels     5
Routes archived    5095
Restores           12
Scheduled runs     170
Oldest backup      2026-05-31T03:00:04+00:00
Latest backup      2026-08-29T03:00:04+00:00

Archive retention  90 day(s)
Backups kept       127
Backup storage     1.1 MB
Database size      112.0 KB

Cinque tunnel sotto controllo, 170 cicli di backup programmati, poco più di un mega di spazio occupato per mesi di storico e un database che sta in 112 KB. Il campo dei ripristini segna dodici ma si tratta dei miei test che ogni tanto lancio a tradimento, per fortuna non ho più dovuto usarlo per davvero (anche se i test hanno comunque sovrascritto tunnel di produzione), è il motivo per cui oggi mi fido a lasciarlo lì a lavorare da solo.

Dovrei prevedere anche delle conservazioni più a lungo termine (mensili, annuali), ma è una caratteristica che non è ancora disponibile, mi sono già promesso di tornarci sopra e lavorarci.

In conclusione

È un software piccolo e per certi versi banale, ma per come lavoro io è ormai fondamentale.
Non fa niente di spettacolare: è un’assicurazione contro la tua stessa distrazione.

Trovi tutto su tikkamasala.gioxx.org e sul repo github.com/gioxx/TikkaMasala. Se lo provi, se ci trovi un bug o se hai idee per migliorarlo, le Issue su GitHub sono il canale più rapido per arrivare a me. Per tutto il resto, l’area commenti qui sotto è a tua disposizione, come sempre.

#KeepItSimple

Immagine di copertina: mia, prodotta con l’aiuto dell’intelligenza artificiale che ha lavorato allo sfondo che c’è alle spalle del logo ufficiale di Cloudflare.