Previewomgevingen uitgelegd: een nieuwe kopie van je app voor elke pull request

Een previewomgeving is een tijdelijke kopie van je applicatie, gebouwd vanuit een pull request of branch en bereikbaar op een eigen URL. Reviewers openen een link en testen de wijziging in de browser in plaats van alleen een diff te lezen. Is het werk klaar, dan verdwijnt de omgeving.

Deze gids laat zien waarvoor previewomgevingen nuttig zijn, waarom het beheer ervan lastig kan zijn en hoe ze op Nodion werken.

Wat is een previewomgeving?

Zie het als een tijdelijke stagingomgeving voor één wijziging. Elke pull request, of een branch die je kiest, krijgt:

• een eigen build van de code op die branch,
• een eigen draaiende app met een eigen URL,
• eigen kopieën van de services waarvan de app afhankelijk is, meestal in elk geval een nieuwe database,
• een beperkte levensduur.

Anders dan bij een gedeelde stagingserver hoeft niemand te wachten tot staging vrij is. Een half afgemaakte feature kan het testen van een andere wijziging niet verstoren. Voor hetzelfde idee kom je ook de termen review apps, deploy previews en ephemeral environments tegen.

Waarom teams ze gebruiken

• Draaiende software reviewen, niet alleen code. Een kapotte lay-out, een verwarrende flow of een trage pagina valt in de browser meteen op, maar zie je makkelijk over het hoofd in een diff.
• QA per wijziging. Testers controleren één wijziging los van de rest voordat die wordt gemerged, zodat elke gevonden bug bij precies één pull request hoort.
• Stakeholders zonder ontwikkelomgeving. Designers, productmanagers of een klant openen een link. Geen lokale checkout, geen schermdeling.
• Migraties testen. Een schemamigratie moet tegen een echte database draaien voordat de preview werkt. Een migratie die alleen op één laptop werkt, faalt hier en niet in productie.
• Parallel werken. Vijf open pull requests betekenen vijf previews in plaats van een wachtrij voor één stagingserver.

Wat ze lastig maakt

De app bouwen is het makkelijke deel. De uitdaging zit in alles eromheen.

Databases

Een app zonder data is moeilijk te reviewen, dus de meeste previews hebben een database nodig. Er zijn drie gangbare keuzes: een lege database, een lege database met testdata of een kopie van de productiedatabase. Die laatste optie is verleidelijk, maar zo komen echte klantgegevens, inclusief persoonsgegevens, terecht in veel tijdelijke omgevingen waar meer mensen bij kunnen. Bij een grote database kost het kopiëren bovendien veel tijd. Voor de meeste teams is een lege database met een seed-script voor realistische demodata de veiligere standaardkeuze.

Secrets

Een preview draait code die nog niet is gereviewd. Toegangsgegevens voor productie horen daar niet thuis. Geef previews test- of sandboxsleutels voor betaaldiensten, e-mail en API's van derden, zodat een bug in een branch geen echte creditcard kan belasten en geen echte klanten kan mailen.

URL's en callbacks

Elke preview heeft een andere hostnaam. OAuth-redirect-URL's, webhook-endpoints, CORS-regels en cookies die aan je productiedomein zijn gekoppeld, kunnen stukgaan. Apps die hun eigen base URL uit de configuratie lezen, in plaats van het productiedomein hard te coderen, hebben hier veel minder last van.

Kosten en opruimen

Elke open preview draait een app, plus een nieuwe database voor elke database die aan de bovenliggende app is gekoppeld. Tien open pull requests kunnen tien extra omgevingen betekenen, en een vergeten preview blijft draaien tot iemand hem sluit. Het opruimen moet automatisch gebeuren; daarom horen previews vanzelf te verlopen.

Zo werken previewomgevingen op Nodion

Op Nodion horen previews bij elke applicatie die vanuit een Git-repository wordt gedeployd:

• Zet ze aan in de Settings van de app.
• Eén preview per pull request of branch. Elke preview is een tijdelijke app met een eigen URL.
• Handmatig of automatisch. Maak handmatig een preview aan, of laat Nodion er automatisch een aanmaken voor pull requests.
• Een nieuwe database. Voor elke database die aan de app is gekoppeld, krijgt een preview een eigen lege database, nooit een kloon van je productiedata. Volumes, buckets en e-mailzones worden niet gekopieerd.
• De instellingen van de app gaan mee. Een preview start met een kopie van de omgevingsvariabelen van de app, secrets inbegrepen. De variabelen van gekoppelde databases wijzen naar de verse databases van de preview; al het andere, ook sleutels en URL's van andere services, wordt ongewijzigd gekopieerd, dus controleer het. Nodion voegt NODION_PREVIEW=1, NODION_PR_NUMBER, NODION_BRANCH en NODION_PARENT_APP toe.
• Previews verlopen na een aantal dagen zonder deploy (standaard 7, in te stellen in de instellingen van de app). Tot die tijd kun je elke preview opnieuw deployen of sluiten via het tabblad Previews van de app.
• Alleen Git-apps. Apps die vanuit een kant-en-klare image zijn gedeployd, hebben geen previews.

De nieuwe database is een bewuste keuze: gekoppelde previewdatabases starten leeg en bevatten dus geen productiedata. Controleer ook de gekopieerde sleutels en URL's, zodat previewcode daarmee niet bij productiesystemen kan. De keerzijde is dat je app moet kunnen starten met een lege database. Dat is sowieso de moeite waard om goed te regelen.

Om te beginnen koppel je je repository onder Git-integraties, maak je daaruit de app aan en zet je previews aan in de instellingen. Alle details staan in de documentatie over applicaties.

Een typische reviewcyclus

1. Een developer opent een pull request. Met automatische previews aan start er een preview voor, met een eigen URL en een lege database.
2. De developer zet de previewlink in de pull request. Reviewers, QA en de product owner proberen de wijziging in de browser.
3. Feedback leidt tot nieuwe commits. Deploy de preview opnieuw vanuit het tabblad Previews om de nieuwste code aan de reviewers te laten zien.
4. Is de wijziging goedgekeurd en gemerged, sluit dan de preview of laat hem vanzelf verlopen.

Niemand hoefde een plek op staging aan te vragen, en Nodion maakte voor de gekoppelde database een nieuwe, lege database aan. Controleer alle andere gekopieerde sleutels en URL's voordat je previewcode draait, want die verwijzen nog steeds naar dezelfde systemen als in de instellingen van de app.

Maak je app klaar voor previews

• Voer migraties automatisch uit bij het deployen of starten van de app, zodat een verse database zonder handmatige stappen het actuele schema krijgt.
• Voeg een seed-script toe dat een testlogin en wat demo-inhoud aanmaakt. Reviewers moeten bij de eerste klik al iets nuttigs zien.
• Lees de base URL uit een omgevingsvariabele in plaats van je productiedomein hard te coderen.
• Zet neveneffecten in testmodus als NODION_PREVIEW is gezet: betalingen, e-mails en alles wat naar andere systemen schrijft. Previews erven de secrets van de app, dus zonder die check gebruikt een preview je productiesleutels.
• Houd pull requests klein. Een preview voor één gerichte wijziging is veel makkelijker te reviewen dan een preview voor een week werk.

Wanneer je ze kunt overslaan

Voor een soloproject met een paar wijzigingen per week kan een lokale set-up plus productie genoeg zijn. Previews betalen zich terug zodra meer dan één persoon wijzigingen reviewt, test of goedkeurt, of als databasemigraties bij je vaste werk horen.

Previews zitten bij elke Git-app op Nodion, naast processen, logs, metrics en auto-deploy. Zie Applicaties voor het volledige overzicht.