Deploy Node.js din GitHub: checklist pentru build, variabile și runtime

Răspunsul scurt

Pentru un deploy Node.js reproductibil din GitHub, repository-ul trebuie să conțină toate fișierele necesare și să definească clar versiunea Node, dependențele, build-ul, comanda de start și portul. Secretele trebuie configurate separat de cod.

Un proiect care rulează pe laptop nu este automat pregătit pentru un mediu curat de build.

1. Fixează versiunea Node.js

Documentează versiunea compatibilă în proiect. Evită să depinzi de versiunea instalată accidental pe calculatorul unui dezvoltator.

Testează proiectul într-un mediu curat cu aceeași versiune pe care vrei să o folosești la deployment.

2. Commit-uiește lockfile-ul corect

Dacă folosești npm, pnpm sau Yarn, păstrează fișierul de lock în repository. Acesta ajută la instalarea acelorași versiuni de dependențe.

Nu combina mai multe lockfile-uri fără un motiv clar. Build-ul trebuie să știe ce manager de pachete folosește proiectul.

3. Separă build de start

Multe aplicații au două etape:

1. build — compilează sau pregătește aplicația;
2. start — pornește serverul rezultat.

Verifică ambele comenzi local într-un mediu curat. Un build reușit nu dovedește că procesul de runtime rămâne pornit.

4. Ascultă pe portul configurat

Aplicația trebuie să folosească portul primit din configurația mediului, nu o valoare fixă care funcționează doar local.

De asemenea, verifică interfața pe care ascultă serverul. Un proces pornit dar inaccesibil din rețeaua containerului va părea „online” doar în logul propriu.

5. Nu pune secrete în Git

Configurează separat:

• parole;
• chei API;
• stringuri de conexiune;
• tokenuri;
• chei de semnare.

Nu commit-ui .env cu valori reale. Dacă un secret a ajuns în istoric, rotația lui este mai importantă decât simpla ștergere din ultimul commit.

6. Verifică variabilele de build și runtime

Unele framework-uri includ anumite valori în bundle la build. Altele le citesc doar la runtime.

Clasifică variabilele și verifică dacă cele destinate serverului pot ajunge accidental în codul trimis browserului.

7. Decide unde stau datele

Nu presupune că filesystem-ul aplicației este spațiu persistent. Upload-urile, baza de date și fișierele importante trebuie să aibă o strategie clară.

Pentru modificări de schemă, planifică migrarea bazei de date separat de rollback-ul aplicației.

8. Folosește logurile

Logurile trebuie să indice suficient context pentru erori fără să expună secrete.

Verifică:

• eroarea de build;
• eroarea de pornire;
• conexiunea la baza de date;
• variabile lipsă;
• portul;
• erorile HTTP ale aplicației.

9. Testează înainte de domeniul final

Pe URL-ul de deployment, verifică:

• pagina principală;
• autentificarea;
• operațiunile de scriere;
• upload-urile;
• joburile de fundal;
• API-urile;
• baza de date;
• emailul tranzacțional.

Conectează domeniul după ce fluxurile importante sunt validate.

10. Planifică rollback-ul

Rollback-ul codului nu anulează automat schimbările din baze de date sau servicii externe. Pentru modificări incompatibile, folosește o strategie de migrare care permite revenirea în siguranță.

Pentru fluxul complet, vezi Deploy din GitHub și Hosting Node.js.