Timestamping Git self-hosted con Docker: una guida

L’attività manuale ripetitiva che stai eliminando è questa: ogni volta che desideri una prova crittograficamente difendibile che un commit Git sia esistito in una certa data, o esegui i comandi di timestamping a mano oppure invii i metadati a un servizio che non controlli completamente. Per startup, team di sviluppo e team attenti alla conformità, questo crea un divario. I passaggi manuali vengono saltati. Le dipendenze esterne sollevano questioni di sovranità dei dati. Gli ambienti regolamentati o air-gapped spesso non possono utilizzare affatto un SaaS gestito.

Il modo difficile è eseguire OpenTimestamps da soli e occuparsi di ogni ricevuta. Il modo pratico è distribuire Timestamp GIT come applicazione Docker self-hosted: la stessa automazione basata su GitHub App, l’ancoraggio notturno su Bitcoin e i badge di verifica girano su un’infrastruttura di tua proprietà.

Se hai bisogno di un ripasso sul perché la prova di esistenza è importante nel software prima di continuare, consulta Proof of Existence in Software: A Beginner’s Guide.

Perché self-hostare il timestamping Git?

Self-hostare Timestamp GIT non significa evitare il servizio gestito. Significa eseguire la stessa automazione dietro il tuo firewall, con il tuo volume di dati, la tua licenza e le tue regole di rete. Questo è importante quando:

• Hai bisogno di sovranità dei dati e non vuoi che i metadati dei commit lascino il tuo ambiente oltre il passaggio di ancoraggio su Bitcoin.
• Operi in un contesto regolamentato o air-gapped in cui le connessioni SaaS di terze parti sono limitate.
• Vuoi il pieno controllo sulle credenziali della GitHub App, sulla posizione di archiviazione e sull’accesso ai log.
• Hai bisogno di una distribuzione adatta agli audit che rimanga sotto il controllo operativo del tuo team.

L’opzione Docker self-hosted ti offre la stessa pipeline automatizzata: installa la GitHub App una sola volta, collega i repository e lascia che l’istanza raggruppi gli hash dei commit ogni notte, costruisca le prove Merkle e le ancori su Bitcoin. Dopo la configurazione iniziale, non c’è alcun passaggio manuale di timestamping.

Configurazione una tantum: distribuire Timestamp GIT con Docker

La distribuzione è un singolo stack Docker Compose con due servizi: l’applicazione Timestamp GIT e un’istanza Valkey utilizzata come coda degli hash.

Crea un file docker-compose.yml con la configurazione esatta della documentazione del prodotto:

services:
  timestampgit:
    image: rue1401/timestampgit:prod
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - ./license.lic:/app/license.lic:ro
    restart: unless-stopped
  valkey:
    image: valkey/valkey:8
    restart: unless-stopped

Quindi esegui:

docker compose pull
docker compose up -d
docker compose logs -f timestampgit

L’applicazione diventa disponibile all’indirizzo http://localhost:8080 dopo l’avvio. Al primo avvio, una procedura guidata ti guida attraverso la connessione della tua GitHub App e la configurazione della tua istanza. È qui che completi l’integrazione una tantum. Non installi nulla sulle macchine degli sviluppatori e non ripeti passaggi manuali di timestamping in seguito.

Hai bisogno di un file di licenza montato in ./license.lic. Una licenza demo a tempo limitato è disponibile compilando il modulo di richiesta sulla pagina Docker License con nome, azienda, email e numero di telefono facoltativo. Per l’uso in produzione, utilizza una licenza commerciale.

Dopo il completamento della procedura guidata, il processo di timestamping continuativo è completamente automatizzato.

La pipeline automatizzata: dal commit all’ancoraggio su Bitcoin

Una volta distribuita, l’istanza self-hosted esegue lo stesso flusso di lavoro a configurazione zero del servizio gestito Timestamp GIT.

Rilevamento dei commit

Esistono due modalità di rilevamento:

• Modalità Standard (GitHub App): la GitHub App rileva i nuovi commit tramite webhook. Legge solo l’hash del commit HEAD di ciascun repository monitorato e invia quell’hash alla tua istanza self-hosted.
• Modalità Enterprise ZK: una GitHub Action di 12 righe viene eseguita sulla tua infrastruttura e invia solo l’hash del commit all’API di Timestamp GIT. In questa modalità, il codice sorgente non lascia mai il tuo ambiente e l’istanza Timestamp GIT non necessita di accesso in lettura al repository sorgente.

Coda degli hash e raggruppamento notturno

Gli hash dei commit in arrivo vengono archiviati nella coda basata su Valkey. Ogni notte, un worker cron all’interno del container Timestamp GIT:

1. Raggruppa tutti gli hash in sospeso per ciascun repository.
2. Crea un file manifest giornaliero (.txt) per ogni repo.
3. Costruisce un albero di Merkle in modo nativo.
4. Crea le prove OpenTimestamps utilizzando calendari OTS pubblici.
5. Ancora la radice di Merkle nella blockchain Bitcoin.

Consegna delle prove

Il manifest e i file di ricevuta .ots vengono inviati a un ramo dedicato ai timestamp o a un repository ombra, a seconda di come hai configurato la GitHub App. Questo avviene automaticamente dopo la conferma dell’ancoraggio su Bitcoin.

La conferma su Bitcoin richiede normalmente alcune ore, quindi le prove non compaiono immediatamente dopo la mezzanotte. Se committi alle 15:00, quell’hash viene prelevato dal successivo ciclo notturno e viene tipicamente ancorato e consegnato alcune ore dopo.

Monitoraggio e gestione dei guasti

Puoi monitorare lo stato di ancoraggio direttamente tramite gli endpoint API esposti dalla tua istanza self-hosted.

Endpoint di stato

Per qualsiasi repository pubblico, puoi interrogare:

curl https://timestampgit.example.com/api/statusLast/acme/checkout-service

Questo restituisce JSON con le informazioni sull’ultimo blocco Bitcoin ancorato.

curl https://timestampgit.example.com/api/statusCount/acme/checkout-service

Questo restituisce il conteggio totale dei commit effettuati e timestampati.

curl https://timestampgit.example.com/api/statusSummary/acme/checkout-service

Questo restituisce un riepilogo combinato adatto ai badge Shields.io.

I repository privati aggiungono un HMAC crittografato all’URL, così solo gli utenti autorizzati possono visualizzare il loro stato. L’HMAC è specifico per la tua istanza server self-hosted.

Dashboard pubblica

Ogni repository dispone anche di una dashboard di stato pubblica all’indirizzo:

https://timestampgit.example.com/status/{user}/{repo}

Questa pagina mostra la longevità delle prove, la data del primo ancoraggio, la regolarità giornaliera, i dati di blocco e transazione Bitcoin, una heatmap di calendario, un CSV di audit scaricabile e un certificato PDF.

Scenari di guasto

• Se il worker cron fallisce, controlla i log del container:

docker compose logs -f timestampgit

• Se la rete Bitcoin ritarda la conferma, gli endpoint di stato non mostreranno ancora un nuovo ancoraggio. Di solito è temporaneo.
• L’istanza self-hosted archivia i suoi dati nel volume ./data. Riavviare o ricreare i container non fa perdere gli hash in coda o la configurazione.
• Configura avvisi basati sull’API di stato o sull’output dei log. Un controllo giornaliero di /api/statusLast è sufficiente per la maggior parte dei team. Se la data dell’ultimo ancoraggio smette di avanzare, indaga sul container e sull’accesso di rete in uscita.

Best practice per il timestamping Git self-hosted

• Limita l’accesso di rete all’host Docker. Usa regole firewall e reverse proxy. Esponi solo le porte che devono essere raggiungibili dai webhook GitHub o dalla tua rete interna.
• Esegui il backup del volume ./data e del file license.lic. Il volume contiene gli hash in coda e la configurazione dell’istanza. Il file di licenza deve rimanere leggibile dal container.
• Usa una GitHub App dedicata con permessi minimi. In Modalità Standard, l’app necessita di accesso in sola lettura ai repository sorgente e di accesso in lettura-scrittura al repository di destinazione dove vengono archiviate le prove. La Modalità Enterprise ZK richiede solo l’accesso in lettura-scrittura al repository di destinazione.
• Preferisci un repository ombra per le prove. Questo mantiene pulito il repository principale e separa la cronologia del sorgente dalle ricevute di timestamp.
• Verifica regolarmente i timestamp. Usa la pagina di verifica pubblica o l’API per confermare che le ricevute .ots verifichino ancora rispetto ai dati dei blocchi Bitcoin. Questo è particolarmente importante prima di un evento legale o di conformità.
• Aggiorna deliberatamente le immagini dei container. Usa docker compose pull durante una finestra di manutenzione e verifica la nuova versione su un’istanza di staging prima di passare alla produzione.

FAQ

D: Posso eseguire Timestamp GIT in un ambiente completamente air-gapped?

R: Sì, la versione Docker self-hosted è progettata per la massima sicurezza e può essere eseguita in ambienti air-gapped. Tuttavia, deve ancora ancorare alla blockchain Bitcoin, quindi l’istanza deve avere accesso a Internet in uscita per raggiungere i nodi Bitcoin o i calendari OpenTimestamps. Se è richiesto un air-gap completo, potresti aver bisogno di un proxy o di un relay per il passaggio di ancoraggio.

D: Come ottengo una licenza per la versione Docker self-hosted?

R: Puoi richiedere una licenza demo a tempo limitato compilando il modulo sulla pagina Docker License con nome, azienda, email e numero di telefono facoltativo. Verrà fornito un file di licenza per la valutazione. Per l’uso in produzione, contatta il fornitore per una licenza commerciale.

D: La versione self-hosted richiede una GitHub App?

R: Sì, l’istanza self-hosted di Timestamp GIT utilizza ancora una GitHub App per rilevare i commit e inviare le prove ai tuoi repository. Durante la procedura guidata di configurazione, collegherai le credenziali della tua GitHub App. L’app richiede accesso in sola lettura ai repository sorgente e accesso in lettura-scrittura al repository di destinazione dove vengono archiviate le prove.

D: Quali sono i requisiti di risorse per eseguire Timestamp GIT con Docker?

R: Le informazioni sul prodotto non specificano requisiti di risorse esatti, ma il Docker Compose include due servizi: l’applicazione Timestamp GIT e un’istanza Valkey (compatibile con Redis) per la coda degli hash. Per team di piccole e medie dimensioni, un VPS modesto con 1-2 GB di RAM dovrebbe essere sufficiente. Monitora l’utilizzo delle risorse e scala secondo necessità.

Conclusione

Il timestamping Git self-hosted con Docker elimina il lavoro manuale ripetitivo dalla protezione della prior art. Distribuisci lo stack una volta, colleghi la GitHub App e ogni commit verso un repository monitorato fluisce attraverso una pipeline automatizzata: rilevamento degli hash, raggruppamento notturno, creazione delle prove Merkle, ancoraggio su Bitcoin e consegna delle prove al tuo repository.

Questa è la differenza tra una salvaguardia legale che usi davvero e una che diventa un peso. Se sei pronto a distribuire, inizia con lo stack Docker Compose sopra e richiedi una licenza demo dalla pagina Docker License. Per i team che preferiscono non gestire la propria istanza, il servizio gestito Timestamp GIT offre la stessa automazione senza self-hosting.

Post correlati

• How to Cryptographically Timestamp Git Commits (Without CLI Tools)
• Timestamp GIT Pricing: Plans for Every Developer
• Proof of Existence in Software: A Beginner’s Guide