Voordat u uw self-hosted agentserver upgradet

Een gebruiker die een workflowserver op eigen machines draait, met meerdere workers en een PostgreSQL-database, meldde op de issuetracker van het project dat er na een upgrade werk verdween. Een van de productieworkflows startte onderliggende workflows en wachtte daarna bij een wachtstap tot die terugmeldden. Na een kleine upgrade werden sommige van die wachtende runs verwijderd terwijl ze wachtten. Toen de onderliggende workflows terugmeldden, kregen ze een foutmelding dat de run niet bestond. De database had geen regel meer voor de wachtende runs.

De gebruiker testte meer versies. De versie van vóór de upgrade werkte. Een latere versie was nog steeds kapot. De gebruiker ging terug naar de versie die werkte, en hield elke latere upgrade tegen. Ook bleek de fout te stoppen zodra de bovenliggende workflow de geslaagde runs bewaarde.

De server crashte niet. Runs die wachtten, waren gewoon weg.

Nog drie upgrades, nog drie tools

De andere meldingen die wij lazen, waren luid.

Een gebruiker die een agentbuilder in Docker draait, meldde dat de server na een upgrade van één patchversie niet meer startte. Hij crashte tijdens het opstarten. Een nieuw, leeg datavolume gaf dezelfde crash, dus de opgeslagen gegevens waren niet de oorzaak. De vorige versie startte wel, met dezelfde opzet. Binnen een week meldden nog drie gebruikers dezelfde crash. Een van hen zette de vorige image vast, en de server draaide weer.

Een gebruiker die een agent-API-server draait vanuit de container-image van de leverancier, meldde op het forum van de leverancier dat de container bij het starten vastliep op een importfout. De gebruiker had niet gekozen voor een upgrade. De image-tag in de opzet was dezelfde, maar de image erachter was veranderd: een paar uur eerder werkte alles nog. Een medewerker van de leverancier raadde aan de versie vast te zetten. Daarna zette de gebruiker de image vast op de digest, een vingerafdruk van één precieze image, en had een opzet die werkte.

Een gebruiker die een platform voor LLM-apps in Docker draait, meldde dat na een upgrade over meerdere versies elke kennispagina een serverfout gaf. De gebruiker dacht dat de sprong te groot was en ging alleen naar de volgende minor-versie. De fout bleef. Het log liet zien waarom: de nieuwe code las een databasekolom die niet bestond. Een databasewijziging die de nieuwe versie nodig had, was niet doorgevoerd. Terug op de oorspronkelijke versie werkten de pagina's weer.

Wat de vier gemeen hebben

Elke gebruiker draaide de server zelf, en elke upgrade was een gewone stap vooruit. In drie gevallen was de fout luid: de server startte niet, of een pagina faalde. In één geval bleef de server draaien en verdween er werk.

In alle vier was de uitweg dezelfde: terug naar de versie die werkte, of die versie vastzetten zodat ze niet kon verschuiven. Teruggaan werkte in deze gevallen. Het werkt niet altijd. Heeft de nieuwe versie de database al gewijzigd, dan kan de oude versie die misschien niet lezen. Dan is de weg terug een back-up van vóór de upgrade.

Wie de server bezit, bezit ook de upgrades. Wat er verder nodig is om eigenaar te zijn, leest u in Zelfgehoste AI: zo houdt u uw AI-stack zelf in handen.

Zeven controles voordat u upgradet

Deze controles gelden voor elke self-hosted agent- of workflowserver, ook de onze. Waar EpicStaff een antwoord heeft, staat dat onder de controle.

1. Zet de versie vast die u draait

Een tag als "latest", of een versietag die een leverancier kan verplaatsen, kan onder u veranderen. De forumgebruiker hierboven koos niet voor een upgrade. Noteer de precieze versie die u draait, en laat uw opzet die versie bij naam opvragen. Dan gebeurt een upgrade wanneer u dat besluit.

In EpicStaff: Zet de versie vast: stel IMAGE_TAG in op een release, of check een release-tag uit. EpicStaff werkt zichzelf niet bij. De versie die u draait, verandert alleen als u die zelf verandert. U upgradet wanneer u daarvoor kiest: haal nieuwe code op en bouw opnieuw (pull en rebuild), of stel een nieuwe image-tag in en haal die op (pull).

2. Lees wat er veranderde, voor elke versie ertussen

Lees wat er veranderde in elke versie tussen de versie die u draait en de versie die u wilt, niet alleen in de nieuwste. Let op databasewijzigingen, nieuwe functies die standaard aan staan, gewijzigde instellingen en verwijderde opties. Kunt u niet vinden wat er veranderde, behandel de upgrade dan als een grote en test hem eerst op een kopie (controle 7).

3. Maak een back-up van de database én de bestandsopslag, en test het terugzetten

De database alleen is niet het hele systeem. Geüploade bestanden, documenten en media staan vaak ergens anders. Maak van beide een back-up, op hetzelfde moment. Zet ze daarna één keer terug op een reservemachine, vóór de upgrade. Een back-up die u nooit hebt teruggezet, is een hoop, geen plan.

In EpicStaff: Runverslagen staan in uw eigen PostgreSQL-database. Maak ook een back-up van de bestandsopslag (file store) en het mediavolume.

4. Weet wanneer databasewijzigingen draaien, en waar een fout zichtbaar wordt

Veel servers wijzigen hun database vanzelf wanneer een nieuwe versie start. De ontbrekende kolom hierboven is een teken dat zo'n wijziging niet is doorgevoerd. Zoek uit of uw tool deze wijzigingen bij het starten doorvoert, met de hand, of allebei. Zoek daarna uit waar een fout zichtbaar wordt: op het scherm, in een log, of pas later als een kapotte pagina. Lees het serverlog na de eerste start, voordat uw gebruikers terugkomen.

In EpicStaff: Elke keer dat de server start, voert hij nieuwe databasewijzigingen vanzelf door. Mislukt er een, dan start de server niet, en het containerlog van de server vertelt waarom.

5. Controleer rollen en rechten na de upgrade

Een upgrade kan veranderen wat een ingebouwde rol mag. Een recht waar mensen op rekenden, kan verdwijnen. Meld u na de upgrade aan als elk soort gebruiker en probeer de taken die het meest tellen.

In EpicStaff: De vier ingebouwde rollen worden elke keer dat de server start opnieuw toegepast vanuit een bestand. Laat een nieuwe versie een recht weg uit een ingebouwde rol, dan wordt dat recht verwijderd, en elke wijziging komt bij het starten in het serverlog. Controleer na een upgrade het serverlog op wijzigingen in de ingebouwde rollen. Het rollenbestand verandert geen eigen rollen (custom roles).

6. Ken uw weg terug voordat u hem nodig hebt

Bepaal vóór de upgrade hoe u teruggaat, wie dat besluit, en hoe lang u wacht voordat u het doet. Teruggaan naar de oude image werkte in de vier meldingen hierboven. Is de database al gewijzigd, dan werkt het misschien niet. Dan is de back-up uit controle 3 uw weg terug.

In EpicStaff: Er is geen ondersteunde weg terug. Zet uw back-up terug.

Wat een server moet bewaren als hij uitvalt, leest u in De server valt een keertje uit. Wat telt, is wat er behouden blijft.

7. Upgrade eerst een kopie

Draai de nieuwe versie op een kopie van uw server, met een kopie van echte gegevens, vóór productie. Draai de workflows die het meest tellen, ook een die wacht op een persoon of op een andere workflow, zoals de wachtende runs hierboven. Vergelijk de uitkomsten met productie. Een kopie vangt niet alles. Wel vangt ze een server die niet start, een ontbrekende kolom of een gewijzigde rol, voordat uw gebruikers die tegenkomen. Hetzelfde geldt voor de agents zelf; zie Wat live draait, is niet wat u hebt getest.

Het moeilijke deel komt na de upgrade

In alle vier de meldingen was de upgrade zelf één stap. Het werk kwam daarna: de oorzaak vinden, teruggaan, en in één geval elke latere versie tegenhouden. Dat werk kost minder vóór de upgrade dan erna.

Zet de zeven antwoorden dus op één pagina: de versie die u draait, de versie die u wilt, waar de back-up staat, wanneer u die voor het laatst terugzette, waar het log staat, en wie besluit om terug te gaan. Kies dan de datum.