Ambienti di anteprima spiegati: una copia nuova della tua app per ogni pull request

Un ambiente di anteprima è una copia temporanea della tua applicazione, costruita da una pull request o da un branch e raggiungibile su un proprio URL. Chi esamina la modifica apre un link e la prova nel browser invece di leggere un diff. Quando il lavoro è finito, l'ambiente sparisce.

Questa guida spiega a cosa servono gli ambienti di anteprima, cosa li rende complicati da gestire e come funzionano su Nodion.

Cos'è un ambiente di anteprima?

Pensalo come un ambiente di staging temporaneo per una singola modifica. Ogni pull request, o un branch che scegli tu, riceve:

• una propria build del codice di quel branch,
• una propria app in esecuzione con un proprio URL,
• le proprie copie dei servizi da cui dipende, di solito almeno un database nuovo,
• una durata limitata.

Rispetto a un classico server di staging condiviso, nessuno deve aspettare che si liberi e una feature lasciata a metà non può interrompere il test di un'altra. Per la stessa idea trovi anche i termini review app, deploy preview o ambienti effimeri.

Perché i team li usano

• Esamina l'app in funzione, non solo il codice. Un layout rotto, un flusso poco chiaro o una pagina lenta saltano all'occhio nel browser e sfuggono facilmente in un diff.
• QA per ogni modifica. I tester verificano una modifica isolata prima del merge, quindi ogni bug che trovano appartiene a una sola pull request.
• Coinvolgi chi non ha un ambiente di sviluppo. Designer, product manager o un cliente aprono un link. Niente checkout in locale, niente condivisione dello schermo.
• Test delle migrazioni. Una migrazione dello schema deve girare su un database reale prima che l'anteprima funzioni. Una migrazione che funziona solo su un laptop fallisce qui, non in produzione.
• Lavoro in parallelo. Cinque pull request aperte significano cinque anteprime invece di una coda davanti a un unico server di staging.

Cosa li rende difficili

Fare la build dell'app è la parte facile. Le difficoltà sono tutto ciò che ci sta intorno.

Database

Un'app senza dati è difficile da valutare, quindi la maggior parte delle anteprime ha bisogno di un database. Le scelte comuni sono tre: un database vuoto, un database vuoto con dati di seed, oppure una copia della produzione. Copiare la produzione è allettante, ma porta dati reali dei clienti, compresi dati personali, in tanti ambienti di breve durata che più persone possono aprire. Inoltre diventa lento quando il database è grande. Per la maggior parte dei team, un database vuoto con uno script di seed per dati demo realistici è la scelta predefinita più sicura.

Secret

Un'anteprima esegue codice che non ha ancora passato la review. Le credenziali di produzione non devono stare lì. Dai alle anteprime chiavi di test o sandbox per provider di pagamento, email e API di terze parti, così un bug in un branch non può addebitare una carta reale né mandare email a clienti reali.

URL e callback

Ogni anteprima ha un hostname diverso. URL di redirect OAuth, endpoint dei webhook, regole CORS e cookie legati al tuo dominio di produzione possono smettere di funzionare. Le app che leggono il proprio URL di base dalla configurazione, invece di avere il dominio di produzione scritto nel codice, qui hanno molti meno problemi.

Costi e pulizia

Ogni anteprima aperta esegue un'app, più un database nuovo per ogni database collegato all'app principale. Dieci pull request aperte possono significare dieci ambienti in più, e un'anteprima dimenticata resta attiva finché qualcuno non la chiude. La pulizia deve avvenire senza che nessuno ci debba pensare, ed è per questo che le anteprime dovrebbero scadere da sole.

Come funzionano gli ambienti di anteprima su Nodion

Su Nodion le anteprime fanno parte di ogni applicazione che fa il deploy da un repository Git:

• Attivale nelle Settings dell'app.
• Un'anteprima per ogni pull request o branch. Ogni anteprima è un'app effimera con un proprio URL.
• A mano o in automatico. Crea un'anteprima a mano, oppure lascia che Nodion ne crei una automaticamente per le pull request.
• Un database nuovo. Per ogni database collegato all'app, un'anteprima riceve un proprio database vuoto, mai un clone dei tuoi dati di produzione. Volumi, bucket e zone email non vengono copiati.
• Le impostazioni dell'app vengono copiate. Un'anteprima parte con una copia delle variabili d'ambiente dell'app, secret compresi. Le variabili dei database collegati puntano ai database nuovi dell'anteprima; tutto il resto, comprese chiavi e URL di altri servizi, viene copiato così com'è, quindi controllalo. Nodion aggiunge NODION_PREVIEW=1, NODION_PR_NUMBER, NODION_BRANCH e NODION_PARENT_APP.
• Le anteprime scadono dopo un certo numero di giorni senza deploy (7 per impostazione predefinita, modificabile nelle impostazioni dell'app). Fino ad allora puoi rifare il deploy di ciascuna anteprima o chiuderla dalla scheda Previews dell'app.
• Solo app Git. Le app con deploy da un'immagine già pronta non hanno anteprime.

Il database nuovo è una scelta voluta: i database collegati alle anteprime partono vuoti, quindi non contengono dati di produzione. Controlla anche le chiavi e gli URL copiati, così il codice delle anteprime non può raggiungere i sistemi di produzione attraverso di essi. Il rovescio della medaglia è che la tua app deve saper partire da un database vuoto, cosa che conviene comunque fare bene.

Per iniziare, collega il tuo repository tramite le integrazioni Git, crea l'app a partire da esso e attiva le anteprime nelle sue impostazioni. I dettagli sono nella documentazione delle applicazioni.

Un tipico ciclo di review

1. Uno sviluppatore apre una pull request. Con le anteprime automatiche attive, parte un'anteprima con un proprio URL e un database vuoto.
2. Lo sviluppatore pubblica il link dell'anteprima nella pull request. Reviewer, QA e product owner provano la modifica nel browser.
3. Il feedback si trasforma in nuovi commit. Rifai il deploy dell'anteprima dalla scheda Previews per mettere il codice più recente davanti ai reviewer.
4. Dopo l'approvazione e il merge della modifica, chiudi l'anteprima oppure lasciala scadere da sola.

Nessuno ha dovuto chiedere uno slot di staging, e Nodion ha sostituito il database collegato con uno nuovo. Controlla tutte le altre chiavi e gli URL copiati prima di eseguire il codice dell'anteprima, perché puntano ancora dove puntano le impostazioni dell'app.

Prepara la tua app per le anteprime

• Esegui le migrazioni in automatico quando l'app fa il deploy o si avvia, così un database nuovo riceve lo schema attuale senza passaggi manuali.
• Aggiungi uno script di seed che crei un login di test e qualche contenuto demo. Chi fa la review dovrebbe vedere qualcosa di utile al primo clic.
• Leggi l'URL di base da una variabile d'ambiente invece di scrivere nel codice il tuo dominio di produzione.
• Metti in modalità test gli effetti collaterali quando NODION_PREVIEW è impostata: pagamenti, email e tutto ciò che scrive su altri sistemi. Le anteprime ereditano i secret dell'app, quindi senza questo controllo un'anteprima usa le tue chiavi di produzione.
• Mantieni piccole le pull request. Un'anteprima per una modifica mirata è molto più facile da valutare di una per una settimana di lavoro.

Quando puoi farne a meno

Se lavori da solo a un progetto con poche modifiche a settimana, un ambiente locale e la produzione possono bastare. Le anteprime diventano utili non appena più di una persona esamina, testa o approva le modifiche, oppure quando le migrazioni del database fanno parte del lavoro abituale.

Le anteprime sono incluse in ogni app Git su Nodion, insieme a processi, log, metriche e auto-deploy. Il quadro completo è su Applications.