/dev/push: l'alternativa open source a Vercel

Se se sei alla ricerca di un'alternativa self-hosted a piattaforme come Vercel o Render, in grado di gestire operazioni di push-to-deploy da GitHub per qualunque linguaggio, con downtime prossimo allo zero, domini personalizzati, log in tempo reale e controllo degli accessi, /dev/push offre una soluzione adatta e basata su Docker. La piattaforma mette a disposizione una UI per orchestrare progetti, ambienti e variabili d'ambiente, usa inoltre una pipeline che clona i repository, costruisce l'immagine, avvia container e sostituisce la release attiva quando i check hanno avuto successo. Il risultato è un flusso di lavoro con rollback istantaneo, mapping dei branch verso ambienti differenti e gestione SSL automatica tramite, ad esempio, Let's Encrypt.

L'architettura di /dev/push

Il cuore del sistema è costituito da un webhook da GitHub che innesca un job con cui clonare il repository. Esso esegue i comandi di build, produce un'immagine Docker e lancia un container collegato ad un reverse proxy che pubblica l'applicazione su un dominio dedicato. L'interfaccia consente di associare branch ad ambienti (per esempio main in produzione e develop in staging), di impostare CPU e memoria di default, di definire variabili cifrate e ispezionare i log sia di build che di runtime. La separazione in componenti (backend API, frontend, worker asincroni, database PostgreSQL, cache/queue, reverse proxy..) rende l'intera architettura estensibile.

Preparazione del server e prerequisiti per l'installazione

L'installazione in fase di produzione funziona su Ubuntu o Debian con Docker. Si consiglia comunque di partire da una macchina virtuale appena creata. Prima ancora di lanciare l'installer si devono configurare i DNS: un record A per la dashboard (ad esempio app.example.com) e un wildcard per i deploy (.example.app). Cloudflare mantiene il proxy attivo e imposta la modalità SSL su "Full (strict)" così che il certificato resti convalidato end-to-end. Un passaggio di hardening iniziale (firewall UFW, fail2ban, disattivazione del login root via SSH e aggiornamenti automatici) riduce poi la superficie d'attacco senza complicazioni.

Se si vuole automatizzare la creazione della macchina, gli script di provisioning dedicati possono allocare la VM, configurare l'utente di accesso e impostare le dipendenze. In alternativa è sufficiente creare l'istanza, assicurarsi che le porte standard (80 e 443) siano raggiungibili e che l'utente possa eseguire i comandi d'installazione con sudo.

Installazione in fase di produzione

Una volta in SSH sulla VM, l'installazione si esegue con un unico comando che scarica e avvia lo script principale:

curl -fsSL https://raw.githubusercontent.com/hunvreus/devpush/main/scripts/prod/install.sh | sudo bash

Lo script prepara Docker e i componenti dell'applicazione, crea un utente dedicato (devpush) e posiziona i file nella directory di servizio. A questo punto si può passare all'utente applicativo e impostare le variabili nell'.env:

sudo -iu devpush
cd devpush
vi .env

Qui si specificano il dominio della dashboard (APP_HOSTNAME), quello dei deploy (DEPLOY_DOMAIN), l'email per Let's Encrypt (LE_EMAIL) e i parametri per l'invio email (ad esempio RESEND_API_KEY). Il primo boot applica anche le migrazioni del database:

scripts/prod/start.sh --migrate

Dopo l'avvio, visitando https://app.example.com si dovrebbe visualizzare la dashboard. Se i certificati non compaiono immediatamente quasi sempre è una questione di DNS non ancora propagato o di LE_EMAIL mancante. Su Cloudflare è bene ricontrollare che i record siano proxati e che la crittografia sia corretta.

Integrazione con GitHub

Per collegare i repository e ricevere gli eventi di push si deve configurare un'App GitHub. Durante la creazione vengono definiti homepage e callback URL per l'autenticazione, l'URL del webhook, i permessi minimi (Contents, Deployments, Pull Requests..) e gli eventi (Push, Repository..). Le chiavi generate, come ID dell'app, client id e chiave privata, vanno incollate nell'.env. Una volta installata l'App sull'account /dev/push potrà autenticare gli utenti via GitHub e attivare i deploy ad ogni push.

Se si desidera limitare l'accesso alla dashboard ai soli membri del team è bene abilitare un file di policy (access.json) per specificare domini o indirizzi. In questo modo chi proverà a registrarsi con un'email non autorizzata verrà bloccato e l'evento potrà essere inviato ad un webhook per l'audit.

Aggiornamenti senza downtime e manutenzione

L'aggiornamento della piattaforma si effettua come utente devpush tramite uno script. Il comando:

scripts/prod/update.sh --all

aggiorna componenti e worker mantenendone la disponibilità. Se si introducono delle modifiche invasive, ad esempio un cambio di schema del database che richiede sequenze di migrazione, è consigliabile l'aggiornamento completo:

scripts/prod/update.sh --full -y

In caso di problemi la struttura dei container facilita il rollback alla release precedente. Sono disponibili utility per migrazioni di database, pulizia delle immagini obsolete e verifica di congruenza dell'.env.

Deploy end-to-end con /dev/push

Dalla dashboard, dopo aver effettuato il login su GitHub, si deve creare un progetto e collegare il repository. La seconda fase prevede di definire l'immagine di base nel progetto (ad esempio node:20-alpine per JavaScript o python:3.12-slim per Python), i comandi di build, di start e le variabili d'ambiente. A questo punto si può premere "Deploy” o eseguire git push sul branch. L'evento raggiungerà /dev/push, partirà il job di build, il container verrà avviato (isolato) e, superati i check, sarà effettuato lo swap sulla nuova versione senza interrompere il traffico.

Un servizio Python con FastAPI prevede ad esempio di impostare python:3.12-slim, eseguire l'installazione delle dipendenze come comando di build e richiamare la variabile $PORT fornita dall'ambiente:

# Build
pip install --upgrade pip && pip install -r requirements.txt
# Start
uvicorn app.main:app --host 0.0.0.0 --port $PORT

La stessa logica si applica ad un'app Node.js o a un progetto PHP. L'importante è che il processo principale ascolti su $PORT e che il check risponda in tempi compatibili con i timeout di deploy.

Ambienti, domini, SSL e sviluppo locale

La piattaforma supporta la gestione completa degli ambienti. La mappatura permette di tenere build parallele su sottodomini distinti all'interno del DEPLOY_DOMAIN, mentre i domini personalizzati possono essere aggiunti convalidando il DNS. I certificati Let's Encrypt vengono rinnovati non appena i record risultano raggiungibili sulla porta 80/443 e non ci si deve preoccupare del ciclo di vita TLS. Anche con Cloudflare il proxy TLS resta comunque trasparente rispetto ai container.

L'interfaccia offre stream live di log per le fasi di build e per il runtime delle applicazioni. I log si possono filtrare rapidamente per individuare errori ed è possibile inviarli verso stack esterni. Per quanto riguarda invece le metriche, la piattaforma funziona anche out-of-the-box senza integrazioni.

Lo stack "dev" di /dev/push replica la composizione dei servizi in locale. Una sessione tipica prevede l'installazione delle dipendenze, la copia dell'.env d'esempio e l'avvio:

scripts/dev/install.sh
cp .env.dev.example .env
scripts/dev/start.sh

Con Docker Desktop i container partono rapidamente e i volumi montati supportano l'hot-reload in corso di sviluppo. Le migrazioni del database in ambiente dev si applicano con uno script dedicato, mentre i worker richiedono un riavvio ogni volta che si modificano le code-path.

In mancanza dei certificati si deve verificare che i record DNS puntino all'IP corretto e che LE_EMAIL sia valorizzata. Su Cloudflare si deve controllare la modalità "Full (strict)". Se i deploy non partono a seguito di un push è necessario entrare nelle impostazioni dell'App GitHub, rivedere i permessi e l'URL del webhook. Nel caso di migrazioni fallite sono disponibili degli script di migrazione dedicati.

Conclusioni

/dev/push è un'alternativa open source e self-hosted a Vercel, Render e piattaforme simili per il coding. Permette infatti di creare e distribuire applicazioni in qualunque linguaggio tra cui Python, JavaScript e PHP con aggiornamenti senza interruzioni, log in tempo reale, domini personalizzabili e variabili d'ambiente.