Checklist di handoff per app pronta alla produzione per self-hosting

Cosa significa nella pratica “consegna pronta per la produzione"

Una consegna pronta per la produzione significa che ops può eseguire l'app senza dover indovinare. Possono distribuire una versione nota, confermare che è sana, rispondere agli alert e recuperare da una release o un outage. Se una qualsiasi di queste attività dipende dalla memoria di un singolo sviluppatore, la consegna non è completa.

Tratta l'handoff come un pacchetto che risponde a una domanda: se i creatori originali sparissero per una settimana, ops riuscirebbe comunque a mantenere il sistema sicuro e disponibile?

Un pacchetto solido di solito copre cosa fa l'app, come si riconosce uno stato “sano”, come funzionano le release (deploy, verifica, rollback), dove vive la configurazione, come si gestiscono i segreti e come monitorare, fare backup e rispondere agli incidenti.

Ugualmente importante è cosa non include. Un handoff non è la promessa di aggiungere funzionalità, rifattorizzare, ridisegnare schermate o “pulire le cose dopo”. Quelli sono progetti separati con il loro scope.

Prima di dichiararlo completo, mettetevi d'accordo su ownership e tempi di risposta. Per esempio: ops si occupa dell'uptime e dei deploy; il product team dell'roadmap; il team di sviluppo fornisce una finestra di supporto post-handoff definita per fix e domande.

Crea un inventario di sistema semplice (cosa gira dove)

Ops può possedere solo ciò che riesce a vedere. Un inventario semplice di una pagina evita congetture durante i deploy, gli incidenti e le verifiche. Mantienilo in linguaggio chiaro e specifico.

Elenca ogni parte in esecuzione e dove si trova: API backend, web app, worker in background, job schedulati e come le app mobile si connettono. Anche se i client iOS/Android sono distribuiti tramite store, dipendono comunque dallo stesso backend.

Includi i servizi esterni di cui l'app non può fare a meno. Se usi PostgreSQL, una queue, object storage o API di terze parti (pagamenti come Stripe, messaggistica, email/SMS, Telegram), scrivi il nome esatto del servizio e a cosa serve.

Riporta i requisiti di rete così l'hosting non diventi un laboratorio di prova ed errore: domini necessari (app, api, admin), porte e protocolli, chi rinnova i certificati TLS, dove è gestito il DNS e eventuali allowlist in ingresso/uscita.

Infine, annota il carico atteso con numeri pratici: picco di richieste al minuto, utenti attivi, dimensioni tipiche dei payload, dimensione attuale del database e crescita prevista. Anche range approssimativi aiutano ops a impostare limiti e alert.

Se hai costruito con AppMaster, inventaria il backend generato, la web app e le integrazioni così ops sa cosa deve essere distribuito insieme.

Prepara la configurazione degli ambienti (senza esporre segreti)

Le configurazioni sono spesso il punto in cui i setup di produzione falliscono: troppo spesso vivono nella testa di qualcuno. Tratta la configurazione come un deliverable. Ops dovrebbe poter vedere quali impostazioni esistono, cosa cambia per ambiente e come modificarle in sicurezza.

Inizia nominando ogni ambiente che esiste oggi, anche quelli temporanei. La maggior parte dei team ha dev, staging e production, più copie come “production-eu” o “staging-us”. Nota quale ambiente è usato per test di release, migrazioni dati e simulazioni di incidente.

Fornisci un unico riferimento di config che elenchi nomi di variabili e valori di esempio sicuri (mai credenziali reali). Rendi i placeholder evidenti.

Il tuo pacchetto di handoff dovrebbe includere:

• Un elenco degli ambienti e a cosa serve ciascuno
• Un riferimento delle chiavi di config (env var o chiavi di file di config), tipo atteso e un valore d'esempio non segreto
• Differenze note tra gli ambienti (feature flag, rate limit, dimensione cache, modalità email, livello di logging)
• Valori di default e cosa succede se manca una chiave
• Dove è memorizzata la config e come viene applicata durante il deploy

Aggiungi un processo semplice per le modifiche. Per esempio: richiesta in ticket, review dal service owner, applicazione prima in staging, poi promozione in produzione in una finestra programmata con un piano di rollback se aumentano gli errori.

Se stai esportando e self-hostando un'app AppMaster, mantieni la stessa regola: consegna un set pulito e documentato di chiavi di configurazione insieme al codice generato in modo che ops possa eseguirlo in modo coerente tra gli ambienti.

Segreti e credenziali: storage, rotazione e accesso

I segreti sono il modo più rapido con cui un handoff pulito può trasformarsi in un incidente di sicurezza. L'obiettivo è semplice: ops deve conoscere ogni segreto necessario all'app, dove è conservato, chi può leggerlo e come cambiarlo senza downtime.

Inizia con una lista breve di segreti che ops può scansionare in un minuto. Per ogni voce, annota cosa sblocca (database, SMTP, Stripe, chiave JWT), dove vive (vault, secret store cloud, Kubernetes Secret, file cifrato) e chi ne è responsabile per la rotazione.

Scrivi i passaggi di rotazione come una ricetta, non una policy. Includi l'ordine esatto, quanto a lungo il vecchio segreto deve rimanere valido e l'unico controllo che dimostra che ha funzionato.

Checklist di rotazione (esempio)

Usa questo schema per ogni segreto:

• Crea il nuovo valore del segreto e salvalo nel secret manager approvato.
• Distribuisci la modifica di config in modo che l'app usi il nuovo valore.
• Verifica: login, pagamenti o chiamate API vanno a buon fine e gli errori non aumentano.
• Revoca il vecchio segreto e conferma che non funziona più.
• Registra la data di rotazione, chi l'ha eseguita e la prossima scadenza.

Sii esplicito sulle aspettative di cifratura. I segreti devono essere cifrati a riposo nello store e protetti in transito (TLS) tra l'app e le sue dipendenze. Non mettere mai segreti nel controllo sorgente, negli artifact di build o in documenti condivisi.

Definisci l'accesso break-glass. Se un outage blocca l'accesso normale, specifica chi può approvare l'accesso d'emergenza, quanto dura e cosa deve essere auditato dopo.

Pacchetto di deployment: artifact, versioni e rollback

Ops può possedere solo ciò che può riprodurre. Un buon pacchetto di deployment rende semplici tre domande: cosa stiamo eseguendo esattamente, come lo distribuiamo di nuovo e come torniamo indietro velocemente se qualcosa si rompe?

Includi una “bill of materials” chiara per la build. Nomina il tipo di artifact e come verificarlo, non solo dove risiede:

• Dettagli artifact: nome/tag dell'immagine container (o nome del binario/pacchetto), versione dell'app, data di build, checksum
• Riferimento sorgente: tag di release o hash del commit usato per costruire, più eventuali flag di build rilevanti
• Target supportati: VM, container (Docker) o Kubernetes, e quale è il default raccomandato
• Passaggi di deployment: prerequisiti (runtime, database, storage), ordine esatto e tempo tipico di deploy
• Migrazioni database: come vengono eseguite (auto all'avvio o manuali), dove sono i log e come confermare il successo

Aggiungi un piccolo esempio concreto. Per esempio: “Distribuire v1.8.2 aggiornando il tag dell'immagine, eseguendo le migrazioni, quindi riavviando i worker web. Se i health check falliscono entro 10 minuti, tornare a v1.8.1 e fermare il job di migrazione.”

Rollback, senza congetture

Un piano di rollback dovrebbe leggere come istruzioni eseguibili alle 2 del mattino. Deve indicare:

• Il segnale che attiva il rollback (error rate, health check fallito, login rotto)
• L'ultima versione nota buona e dove è memorizzata
• Se le modifiche al database sono reversibili e cosa fare se non lo sono

Se l'app è costruita con AppMaster ed esportata come sorgente per il self-hosting, includi la versione del codice generato, le istruzioni di build e le aspettative runtime in modo che ops possa ricostruire la stessa release in seguito.

Monitoring e alerting: cosa misurare e quando pagare

Un handoff non è completo finché ops non riesce a vedere cosa fa l'app e non viene avvisato prima che gli utenti si lamentino.

Metti d'accordo cosa deve esistere nei log e dove finiscono (file, syslog, piattaforma di log). Assicurati che i log siano sincronizzati nel tempo e includano un request o correlation ID così gli incidenti sono tracciabili end-to-end.

Di solito vuoi log applicativi (eventi chiave e fallimenti), log di errori (stack trace e job falliti), access log (richieste e codici di stato), audit log (azioni admin ed export) e log infrastrutturali (restart, pressione nodi, problemi disco).

Poi definisci un piccolo set di metriche che riflettano l'impatto utente e la salute del sistema. Se ne scegli solo cinque: latenza (p95/p99), error rate, saturazione (CPU/memoria/disk), profondità delle code e controlli di disponibilità dall'esterno della tua rete.

Le regole di alert devono essere inequivocabili: cosa le attiva, gravità (pagina vs ticket), chi è on-call e quando scalare. Aggiungi uno snapshot di dashboard “buono” e una breve nota che descriva cosa è normale (range tipico di latenza, error rate atteso, profondità usuale delle code). Quel contesto evita alert rumorosi e aiuta i nuovi responder ad agire rapidamente.

Backup e ripristino: rendere il restore ripetibile

I backup non sono qualcosa che “hai”. Sono qualcosa da cui puoi ripristinare, su richiesta.

Scrivi l'ambito esatto: database, file storage (upload, report, fatture) e i pezzi che spesso si dimenticano, come la config che non è in codice e le chiavi di cifratura necessarie per leggere i dati protetti.

Mantieni gli obiettivi in termini semplici. RPO è quanto dato puoi permetterti di perdere (per esempio, 15 minuti). RTO è quanto tempo puoi stare giù (per esempio, 1 ora). Scegli numeri concordati con il business, perché guidano costi e sforzi.

Includi:

• Cosa è backuppato, dove è conservato e la retention
• Chi può eseguire backup e restore e come si approva l'accesso
• Una procedura passo-passo di restore con controlli di verifica
• Dove sono i log di restore e cosa significa “successo”
• Modalità di errore comuni (chiave sbagliata, bucket mancante, mismatch di schema) e la soluzione

Se esporti e self-hosti un'app costruita con AppMaster, includi i passaggi di restore per PostgreSQL oltre agli eventuali bucket di storage esterni e le chiavi usate per i campi cifrati.

Programma un drill di restore. Registra il tempo, cosa è andato storto e cosa avete cambiato così il prossimo restore sarà più veloce e meno stressante.

Runbook e on-call: come ops gestisce incidenti reali

Un handoff non è reale finché qualcuno non può essere pagato alle 2 del mattino e risolvere il problema senza dover indovinare. I runbook trasformano la conoscenza tribale in passaggi che un on-call può seguire.

Inizia con gli incidenti che ti aspetti accadano per primi: outage totale, richieste lente e un deploy che rompe qualcosa. Mantieni ogni runbook corto. Metti i controlli più veloci in cima così i responder ottengono segnale in pochi minuti.

Cosa contiene un buon runbook

Mantieni la struttura coerente così è leggibile sotto pressione:

• Cosa vedono gli utenti e come confermarlo (esempio: error rate sopra X%, checkout che fallisce)
• Controlli iniziali (stato del servizio, deploy recenti, salute delle dipendenze, disco/CPU, connessioni DB)
• Controlli successivi (quali log aprire, dashboard chiave, modifiche di config recenti, profondità delle code)
• Punti decisionali (quando fare rollback, quando scalare, quando disabilitare una feature)
• Escalation (chi è il proprietario dell'app, chi è proprietario dell'infra e quando chiamare ognuno)

Se l'app è stata esportata o self-hostata da AppMaster, includi dove girano i servizi generati, come riavviarli in sicurezza e quali valori di config ci si aspetta per ogni ambiente.

Dopo l'incidente: cattura i fatti giusti

Tieni una breve checklist post-incidente. Registra la timeline, cosa è cambiato per ultimo, i messaggi d'errore esatti, gli utenti interessati e quale azione ha risolto. Poi aggiorna il runbook mentre i dettagli sono ancora freschi.

Controllo accessi e permessi: chi può fare cosa

Ops può possedere un sistema solo se è chiaro chi può toccare cosa e come viene tracciato l'accesso.

Scrivi i ruoli che usate realmente. Per molti team questi sono sufficienti:

• Deployer: distribuisce versioni approvate e avvia rollback
• DB admin: esegue modifiche di schema e restore dei backup
• Read-only: visualizza dashboard, log e config senza modificare
• Incident commander: approva azioni di emergenza durante un outage

Documenta la “policy di accesso” in passi chiari: chi concede l'accesso, dove viene concesso (SSO, cloud IAM, utenti DB, CI/CD, pannelli admin), chi può revocarlo e come controllare che sia rimosso durante l'offboarding.

Non dimenticare gli accessi non umani. Elenca ogni service account e token usato da job, integrazioni e monitoring, con una nota di least-privilege per ciascuno (esempio: “può leggere solo dal bucket X”). Se esporti codice sorgente AppMaster per self-hosting, indica quali env var o file di config definiscono queste identità, ma non incollare mai i valori segreti nel documento di handoff.

Imposta anche le aspettative sui log di audit: cosa deve essere loggato (login, deploy, modifica config, azioni DB admin), chi può leggere i log, retention, dove sono conservati e come richiederli durante un incidente o una verifica.

Sicurezza e compliance in termini semplici

Le note di sicurezza dovrebbero essere leggibili da non specialisti, ma abbastanza specifiche perché ops possa agire. Aggiungi una sintesi di una pagina che risponda: quali dati conserviamo, dove risiedono e chi può accedervi?

Inizia con i tipi di dati: profili clienti, ticket di supporto, metadata dei pagamenti, file. Segnala categorie sensibili come PII (nomi, email, numeri di telefono), credenziali e qualsiasi dato regolamentato rilevante. Se hai esportato il codice sorgente per self-hosting (incluso da AppMaster), indica dove quei dati finiscono nel database e quali servizi possono leggerli.

Poi scrivi le regole di retention e cancellazione in termini pratici. Dì cosa conservi, per quanto e come funziona la cancellazione (soft delete vs hard delete, purge ritardato, backup). Se ci sono hold legali o esigenze di audit, segnala chi approva le eccezioni.

I log spesso perdono più dati dei database. Sii chiaro su dove può comparire PII (access log, error log, eventi analitici) e come ridurlo o mascherarlo. Se un campo non deve mai essere loggato, dichiara quella regola.

Mantieni le approvazioni esplicite:

• Le modifiche all'autenticazione richiedono un approvatore nominato.
• Le modifiche relative ai pagamenti (chiavi Stripe, endpoint webhook, logica di refund) richiedono un approvatore nominato.
• Le modifiche al modello di ruoli e permessi richiedono un approvatore nominato.
• Sono scritte le finestre di patch di sicurezza e le regole per le modifiche di emergenza.

Se puoi aggiungere solo una cosa, aggiungi una nota sull'evidenza: dove sono conservati i log di audit e come esportarli quando qualcuno chiede una prova.

Scenario di esempio: ops prende in carico in una settimana

Ops prende in carico un portale clienti costruito da un piccolo team prodotto e lo sposta su nuova infrastruttura self-hosted. L'obiettivo non è solo “parte”, ma “ops può eseguirlo senza chiamare i creatori”.

Com'è strutturata la settimana

Giorno 1: Ops esegue un primo deploy pulito in un nuovo ambiente usando solo il pacchetto di handoff. L'app parte, ma il login fallisce perché manca una variabile d'ambiente per il provider email. Questa viene aggiunta al template degli env e il deploy viene ripetuto fino a che funziona da zero.

Giorno 2: Scatta il primo alert di prova. Ops causa un fallimento controllato (ferma un servizio o blocca l'email in uscita) e conferma: le metriche mostrano il problema, gli alert raggiungono il canale giusto e il messaggio indica cosa fare dopo.

Giorno 3: Un token scade nel sandbox dei pagamenti. Poiché la posizione delle credenziali e i passaggi di rotazione sono documentati, ops lo sostituisce senza dover indovinare o esporre segreti.

Giorno 4: Cutover DNS. Un record errato punta al vecchio IP e il portale sembra giù per alcuni utenti. Ops usa il runbook per verificare DNS, TLS e health check nell'ordine corretto.

Giorno 5: Primo test di restore del backup. Ops ripristina su un database pulito e dimostra che il portale può caricare dati reali.

Cosa significa “done” dopo 1 settimana

L'app è rimasta in esecuzione per 7 giorni senza fix misteriosi, con un restore riuscito, alert chiari e un deploy ripetibile che ops può fare da solo.

Errori comuni che causano incidenti notturni

Il modo più rapido per trasformare un handoff tranquillo in un incendio alle 2 del mattino è pensare che “abbiamo detto tutto a ops” sia uguale a “ops sa eseguire l'app senza di noi”.

Pattern di fallimento comuni dopo un handoff self-hosted includono segreti condivisi in spreadsheet o chat, rollback che dipendono da uno sviluppatore, backup che esistono ma non sono mai stati testati in restore, alert che suonano tutto il giorno perché le soglie non sono state tarate e dettagli di ambiente che vivono solo nella testa di qualcuno (porte, nomi DNS, cron, permessi cloud).

Esempio: esporti codice sorgente da AppMaster per self-hosting e il primo deploy funziona. Due settimane dopo una modifica di configurazione rompe i login. Se i segreti sono stati passati via chat e il rollback richiede il builder originale, ops perde ore per tornare a “stava funzionando ieri”.

Controlli rapidi prima di dichiarare “handoff completo”

Prima di chiudere il ticket, esegui un breve drill di partenza pulita. Dai il pacchetto di handoff a un singolo ingegnere ops e un ambiente pulito (nuova VM, nuovo namespace Kubernetes o un nuovo progetto cloud). Se riescono a deployare, osservare e recuperare l'app entro un tempo stabilito (per esempio 2 ore), sei vicino al traguardo.

Usa questi controlli:

• Ricostruire e deployare da zero usando solo gli artifact impacchettati, i documenti di config e i runbook (incluso il rollback).
• Verificare che ogni segreto sia nel posto concordato e che i passaggi di rotazione siano scritti e testati.
• Aprire le dashboard e confermare che rispondono a domande basiche: è su, è lento, sta generando errori, sta finendo le risorse?
• Far scattare un alert di prova sicuro per confermare routing delle pagine, proprietari e finestre di quiet hours.
• Eseguire un vero test di restore in un ambiente separato, poi documentare i passaggi esatti e il risultato atteso.

Se esporti codice generato per self-hosting, conferma anche che ops sa dove sono registrati input di build, versioni e tag di release così le release future restano ripetibili.

Passi successivi: finalizzare ownership e mantenere il pacchetto aggiornato

Esegui un'ultima walkthrough con le persone che porteranno il pager. Trattala come una prova generale. Dimostra che deploy, rollback, restore e alerting funzionano tutti con l'esatto pacchetto che stai consegnando.

Una walkthrough finale di solito copre: deploy su un ambiente di test e poi produzione usando gli stessi passaggi, rollback alla versione precedente e verifica del funzionamento, restore da backup in un ambiente pulito e validazione di un controllo semplice (login, creare un record, inviare un messaggio), far scattare un alert di prova e confermare dove trovare log e dashboard durante un incidente.

Rendi l'ownership esplicita. Assegna un owner nominato per ogni runbook (deploy, incidente, restore) e per ogni route di alert (on-call primario, backup, comportamento fuori orario). Se nessuno possiede un alert, verrà ignorato o sveglierà la persona sbagliata.

Scrivi un breve piano Day 2 così ops sa cosa migliorare dopo la prima settimana: tarare soglie, controllare costi, pulire artifact vecchi e rivedere gli accessi. Mantienilo piccolo e time-boxed.

Se hai costruito con AppMaster (appmaster.io), includi il codice sorgente esportato o i dettagli di deployment esatti (cloud, regioni, impostazioni di build, servizi richiesti) così ops può riprodurre l'app senza dipendere dallo workspace originale del progetto. Stabilisci una cadenza semplice per aggiornare il pacchetto ogni volta che cambiano i requisiti, così i runbook non si discostano dalla realtà.