Impuls – pubblica e sincronizza la documentazione con facilità

Oggi rendiamo open-source Impuls, un piccolo container che abbiamo costruito per risolvere un problema che continuavamo a riscontrare: portare un sito web (spesso la documentazione di un progetto per un cliente) dal git push alla pagina servita, senza reinventare l’impianto di deployment ogni singola volta.

Codice di qualità, documentazione di qualità

In eXact lab abbiamo una convinzione tranquilla ma salda: il codice è valido solo quando lo è anche la documentazione che lo accompagna. Un software ingegnoso che nessuno riesce a configurare senza leggere il codice sorgente non è un lavoro
finito, ma un peso per il futuro.

Presentiamo Impuls

La maggior parte delle piattaforme offre una qualche funzionalità di pubblicazione, che attinge il contenuto da un repository git e rimane automaticamente sincronizzata con esso. Ma cosa succede con i progetti dei clienti o la documentazione interna, che non dovrebbero essere generalmente accessibili o sono addirittura un segreto commerciale?

I generatori di siti statici sono fantastici. Si scrive la documentazione del progetto usando Markdown, Restructured Text e simili, si esegue la build, e ne esce un sito web veloce e affidabile. La parte scomoda è tutto ciò che accade dopo: come si serve l’artefatto creato dal generatore di cui ci si fida? Dove viene eseguita la build? Come fa a sapere che il repository è cambiato, quando tutto ciò che si ha è un repository bare sul server di un cliente?

Impuls racchiude tutto questo in un singolo container. Serve il sito sulla porta 80 e un webhook sulla porta 9000 per ricevere i trigger di build. Un reverse proxy, come Traefik, può instradare ciascuno indipendentemente, in modo che il webhook resti pubblico mentre il sito si nasconda dietro un entrypoint accessibile solo via VPN. Su una richiesta valida e firmata con HMAC, Impuls effettua il pull del repository, esegue il comando di build e inizia a servire l’output. Fine.

Sono disponibili due varianti pronte all’uso, impuls-hugo e impuls-zensical, con Hugo e Zensical pre-installati, rispettivamente. L’unica cosa che bisogna effettivamente fornire è l’URL di un repository e un segreto per il webhook.

Problema risolto

Si immagini un repository su un’infrastruttura privata. Tutto ciò che serve è dire a Impuls come accedere al repository e condividere un segreto tra i due.

Nel caso di progetti ospitati su forge, è semplicemente questione di configurare un webhook firmato verso Impuls. Nel caso “forgeless”, un semplice hook post-receive può fare lo stesso.

C’è ampia discrezionalità su come distribuire Impuls, dato che l’endpoint di trigger viene servito su una porta diversa rispetto al sito stesso. Si può usare il proprio reverse proxy preferito per pubblicare l’uno, l’altro o entrambi, in qualsiasi configurazione, dalla più aperta alla più restrittiva.

Provalo

Impuls è concesso in licenza MIT ed è disponibile ora su Codeberg. Se gestisci un sito di documentazione o qualsiasi pagina generata staticamente e sei stanco di soluzioni di deployment fatte su misura, provalo e, se ti va, facci sapere cosa ne pensi. Lo rendiamo open-source proprio perché pensiamo che la risposta alla domanda “come servo questo sito” dovrebbe essere semplice, condivisa e ben documentata, e preferiamo mantenere insieme una buona risposta piuttosto che tante soluzioni private da soli.

Link utili

Impuls su Codeberg: https://codeberg.org/eXact-lab/impuls
Zensical: https://zensical.org/docs/get-started/
Hugo: https://gohugo.io/