De kern: updates op de host, niet in een extra container

Een passende basis is een timer op de host, deployment met een vaste image-digest, duurzame registratie van de update en rollback naar een lokaal bewaarde image. Een aparte updatecontainer is daarvoor niet nodig.

De aanpak is alleen onder voorwaarden haalbaar. Een controle van een externe registry kan niet gegarandeerd iedere keer binnen een seconde klaar zijn. En omdat de gateway als één container opnieuw wordt aangemaakt, zijn nul downtime en verliesvrije afhandeling van lopende verzoeken niet gegarandeerd.

Belangrijk: dit is alleen een ontwerp en implementatiecontract. Er zijn geen bestanden geschreven, tests uitgevoerd of twee externe VPS’en aangepast. Het doel is automatisch herstel bij een mislukte update zolang de host en Docker normaal functioneren. Bij stroomuitval, een niet-beschikbare Docker-daemon of een oude image die zelf niet start, moet het systeem een fout melden; gegarandeerd zelfherstel is dan niet mogelijk.

Wat de huidige configuratie betekent

De releaseworkflow accepteert versietags in de vorm v plus hoofd- en subversie, bijvoorbeeld v3.12. De workflow publiceert latest, 3.12, v3.12 en een korte commit-SHA. Er is geen automatische reeksalias met de naam v3.x. De workflow noemt vier architecturen, maar dat bewijst op zichzelf niet dat iedere release voor al die architecturen succesvol is gepubliceerd (releaseworkflow).

De huidige gatewayservice wordt vanuit broncode gebouwd, luistert op poort 8080 van de host en gebruikt een read-only configuratiemount. De mailservice gebruikt geheugenopslag. De mailcontainer niet opnieuw starten is daarom een harde randvoorwaarde (Compose-configuratie).

De gepubliceerde image start de root-entrypoint. Voor de start is een lokale configuratie voor de modelregistry nodig; die configuratiemap zit niet in de image. Ook na de overstap op een gepubliceerde image moet die configuratie dus op de host beschikbaar blijven (Dockerfile, startcode).

Er zijn bovendien grenzen aan wat een healthcheck kan aantonen. De modelendpoint van de root-entrypoint leest een momentopname van de registry en verstuurt geen echte chatverzoeken. De health-endpoint meldt alleen dat de applicatie leeft. Geen van beide bewijst dat upstreamaccounts zijn opgewarmd of dat een echte chat werkt (modelendpoint, healthroute). Gebruik hierbij niet zomaar de authenticatieregels van een andere handler.

Bij een stopsignaal annuleert de applicatie haar servicecontext; de HTTP-server krijgt vijf seconden om af te sluiten. Een langere Docker-stoptermijn alleen garandeert dus niet dat langlopende streamingverzoeken klaar zijn voordat de container stopt (afsluitlogica).

Buiten de scope: de mailservice aanpassen, accountstatus van een draaiende service synchroniseren, dependencies upgraden, code op afstand ophalen of de lokale ontwikkelbuild veranderen. Ook worden een gelijktijdige omschakeling tussen hosts, nul downtime en verliesvrije afhandeling van lopende verzoeken niet beloofd. Daarvoor zijn onder meer twee instanties, een omschakelbaar toegangspunt en gecontroleerde connection draining nodig.

Zo hoort de updater te werken

Het voorgestelde startpunt is scripts/auto-update.sh; dit script bestaat nog niet. De host heeft onder meer Bash, Docker Engine, de Compose-plugin, curl, jq, flock en Skopeo nodig om alleen de registrymanifesten te lezen. De exacte distributies en versies moeten tijdens de implementatie op de doelhosts worden gecontroleerd.

Laat het script onder een afgeschermd hostaccount draaien en Docker rechtstreeks op de host aanroepen. Mount de Docker-socket of registrycredentials niet in een container. Let wel: een account met Docker-beheerrechten heeft nog steeds ruime macht over de host. Het ontbreken van een socketmount neemt dat risico niet weg.

Werk met digests en duurzame transactiestatus

Gebruik een tag, standaard latest, alleen om te ontdekken of er een nieuwe versie is. Deploy vervolgens altijd een image die is vastgezet op een digest. Compose ondersteunt imageverwijzingen met een digest.1

Houd verschillende identifiers uit elkaar: de digest van het multi-architecturemanifest, de digest van het platformspecifieke manifest en de lokale Docker-image-ID zijn niet onderling uitwisselbaar. Bewaar daarnaast de huidige geaccepteerde image, de vorige werkende image, een eventuele lopende transactie en een registratie van digests die na een mislukking tijdelijk zijn uitgesloten.

Haal vóór een update de image-ID op van de daadwerkelijk draaiende container. Geef die image een eigen lokale bewaartag en controleer eerst of de oude service gezond is. Zo is rollback niet afhankelijk van een nieuwe verbinding met de registry.

Schrijf de status in een strikt gevalideerd gegevensformaat; voer de inhoud nooit uit als shellcode. Schrijf eerst naar een tijdelijk bestand in dezelfde map en vervang het statusbestand daarna atomair. Voor cruciale status moet ook de bestands- en directorystatus duurzaam worden weggeschreven: alleen hernoemen is geen garantie tegen gegevensverlies bij stroomuitval.

Update in gecontroleerde stappen

1. Vraag een vaste bestandslock non-blocking aan. Als een ander proces de lock heeft, stopt deze run stil. Update, herstel, initialisatie en opruimen gebruiken dezelfde lock.
2. Handel een onafgemaakte transactie af voordat je de registry raadpleegt. Controleer het vaste Compose-project, de unieke gatewaycontainer, de configuratiefingerprint en de identiteit van de mailcontainer. Stop bij onverwachte handmatige wijzigingen; neem ze niet automatisch over.
3. Lees alleen de externe manifesten en bereken de juiste digest; download nog geen image-lagen. Bij netwerk-, authenticatie- of parsefouten blijft de huidige service draaien. Een lege digest mag nooit als een nieuwe versie worden behandeld.
4. Is de digest gelijk aan de laatst geaccepteerde versie, dan pullt of herstart het script niets en schrijft het geen updategeschiedenis. Een eerder mislukte digest wordt eveneens overgeslagen totdat er een nieuwe digest is of een beheerder de uitsluiting opheft.
5. Pull de image op basis van de vaste digest. Controleer daarna of de image voor het lokale platform beschikbaar is en of er voldoende schijfruimte is. De oude gateway blijft tijdens het downloaden draaien.
6. Bewaar de oude image en de bijbehorende configuratie en schrijf de fase klaar voor omschakeling duurzaam weg. Maak alleen de gateway opnieuw aan.
7. Controleer de image-identiteit, de containerstatus en de applicatieprobe. Pas na een geslaagde controle wordt de nieuwe versie als geaccepteerd vastgelegd.
8. Mislukt het aanmaken of is de service na het gezondheidsvenster nog niet goed, herstel dan de lokaal bewaarde oude image. Maak alleen de gateway opnieuw aan en voer dezelfde controles uit.
9. Na geslaagde rollback herstel je de duurzame deploymentverwijzing, zet je de mislukte digest op de uitsluitlijst en registreer je de gebeurtenis. Mislukt ook rollback, bewaar dan de herstelbestanden, meld een fout en blijf niet automatisch herstarten.

De volgende shellcommando’s illustreren de richting, maar vormen geen complete of geteste installer. Validatie van de transactie, containeridentiteit en herstel bij onderbrekingen moet nog worden geïmplementeerd:

# Waarden komen uit een gevalideerde configuratie die gewone gebruikers niet kunnen wijzigen.
exec 9>"$LOCK_FILE"
flock -n 9 || exit 0

# Alleen het manifest lezen. Verifieer eerst de authenticatie- en uitvoeropties van Skopeo.
timeout --kill-after=2s 15s \
  skopeo inspect --authfile "$DOCKER_CONFIG/config.json" \
  --raw "docker://$TRACK_IMAGE" \
  </dev/null >"$MANIFEST_TMP"
# Controleer de exitstatus vóór je de digest berekent.
# Verwerk nooit gedeeltelijke uitvoer na een mislukte opdracht.

# NEW_REF moet een gevalideerde ghcr.io-repository@sha256:digest zijn.
timeout --kill-after=5s 600s \
  docker pull "$NEW_REF" </dev/null

# Vooraf zijn de transactie en de lokale rollback-image duurzaam vastgelegd.
APP_IMAGE="$NEW_REF" timeout --kill-after=5s 60s \
  docker compose --project-name "$PROJECT" \
  --project-directory "$DEPLOY_DIR" -f "$COMPOSE_FILE" \
  up -d --no-deps --no-build --pull never app </dev/null

# Bij een fout: OLD_LOCAL_REF is de gecontroleerde, lokaal bewaarde image.
APP_IMAGE="$OLD_LOCAL_REF" timeout --kill-after=5s 60s \
  docker compose --project-name "$PROJECT" \
  --project-directory "$DEPLOY_DIR" -f "$COMPOSE_FILE" \
  up -d --no-deps --no-build --pull never app </dev/null

De Compose-opties voorkomen dat tijdens deze opdracht een build, het starten van afhankelijke services of een extra image-pull plaatsvindt; de opdracht richt zich uitsluitend op app.2 Gebruik geen opdracht die het hele project herstart, wees geen weescontainers of stop alle services.

Een timeout bewijst niet dat een Docker-actie op de achtergrond is beëindigd. Controleer bij zo’n timeout eerst de werkelijke containerstatus en laat herstel pas verdergaan als duidelijk is wat Docker nog uitvoert. Reken bij een harde kill of stroomuitval niet op een exit-trap: herstel moet steunen op de weggeschreven transactie en bij de volgende start voorrang krijgen.

Gezondheidscontrole: wat die wel en niet zegt

Een mogelijke startconfiguratie is een gezondheidsvenster van 60 seconden, een verbindingstime-out van 1 seconde, maximaal 3 seconden per verzoek, een pollinterval van 2 seconden en drie opeenvolgende successen. Dit zijn voorgestelde waarden, geen gemeten resultaten.

• Vraag de lokale modelendpoint op. Vereis HTTP 200, volg geen redirects en controleer de JSON-structuur. Een inlogpagina of proxyfout mag niet als succes tellen.
• Controleer dat de draaiende gatewaycontainer daadwerkelijk de kandidaat-image gebruikt en dat het aantal herstarts niet blijft oplopen. Zo voorkom je dat een oude container ten onrechte een geslaagde controle oplevert.
• Of de modellenlijst niet leeg moet zijn, hangt af van de huidige registryafspraken. Leg geen historisch aantal van achttien items vast als vaste eis.
• Een health-endpoint kan aanvullend zijn, maar start niet automatisch een echte chat die mogelijk quota verbruikt. Echte bedrijfsbeschikbaarheid vraagt om een aparte acceptatietest.

De Compose-configuratie op de VPS

Pas alleen de deploymentkopie op de externe VPS’en aan. Behoud poorten, geheugenlimieten, logging, omgevingsvariabelen, read-only configuratiemounts en de mailconfiguratie. Overschrijf niet de lokale ontwikkelconfiguratie. De image-instelling staat in de gatewayservice (Compose-configuratie).

services:
  app:
    image: "${APP_IMAGE:?Een vastgezette imageverwijzing is verplicht}"
    pull_policy: never

Dit is alleen het te vervangen fragment, niet het volledige Compose-bestand. De deploymentmap moet de complete bestaande servicedefinitie bevatten en de build-instelling van de gateway moet eruit. Bewaar in de deploymentconfiguratie de geaccepteerde digest of de lokale rollbacktag; laat een handmatige herstart niet vanzelf terugvallen op latest.

Controleer ook het bestaande Compose-project en de configuratie op iedere host. Een onverwachte projectnaam kan bijvoorbeeld nieuwe netwerken aanmaken of de verbinding met de mailservice veranderen. Ga er niet van uit dat de projectnaam op de lokale machine gelijk is aan die op beide VPS’en.

Omgevingsvariabelen voor Compose-interpolatie zijn niet automatisch hetzelfde als variabelen in de container. Controleer daarom de bestaande remote instellingen in plaats van aan te nemen dat een omgevingsbestand vanzelf alles doorgeeft. De huidige configuratie schakelt twee experimentele functies expliciet in, terwijl de projectcontext aangeeft dat ze standaard uit horen te staan. Deze taak verandert de schakelaars niet; controleer de waarden op de VPS en neem niet aan dat de lokale configuratie de geïnstalleerde remote versie weergeeft (experimentele instellingen, projectcontext)).

De VPS heeft alleen de deploymentconfiguratie, runtimeconfiguratie en vooraf gebouwde image nodig. Een checkout van de broncode of schrijfrechten op de code-repository zijn niet nodig. Vereist een update een incompatibele configuratiemigratie, dan mag die niet automatisch plaatsvinden zonder een omkeerbaar migratieplan.

Registrytoegang zonder onnodige rechten

Voor een private GHCR-image is een classic personal access token met pakketleesrechten nodig. Controleer of het account bij de image mag en rond, waar vereist, de SSO-autorisatie van de organisatie af. Geef de VPS geen CI-token met schrijfrechten en geen rechten om images of broncode te schrijven of te verwijderen.9

Aanbevolen inrichting:

1. Gebruik per VPS een afzonderlijk, intrekbaar read-only credential. Log in via standaardinvoer, zodat het token niet in argumenten of auditlogs belandt.9
2. Bewaar de Docker-configuratie in een directory voor de updater die alleen door beheerders leesbaar is. Laat de updater en de tool voor manifestinspectie dezelfde, gecontroleerde authenticatieconfiguratie gebruiken.
3. Geef het credential niet door aan de gateway- of mailcontainer. Richt een herinnering voor de vervaldatum en een intrekprocedure in. Bij een authenticatiefout stopt alleen de update; de oude service blijft draaien.

Periodiek uitvoeren met systemd

Systemd is hier de voorkeursoptie. De volgende service- en timerunits zijn voorstellen, geen geïnstalleerde units. Paden en account zijn voorbeelden voor de remote installatie.

[Unit]
Description=Aurora: native image-update en herstel
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=root
WorkingDirectory=/opt/aurora
Environment=DOCKER_CONFIG=/etc/aurora-updater/docker
ExecStart=/opt/aurora/scripts/auto-update.sh
TimeoutStartSec=20min
UMask=0077
Nice=10
IOSchedulingClass=idle
NoNewPrivileges=yes
StandardOutput=journal
StandardError=journal

[Unit]
Description=Aurora: periodieke controle op image-updates

[Timer]
OnBootSec=1min
OnUnitInactiveSec=5min
RandomizedDelaySec=30s
AccuracySec=1s
Unit=aurora-update.service

[Install]
WantedBy=timers.target

Installeer en controleer eerst de dependencies en configuratie. Leg een gezonde oude versie vast en oefen het herstel voordat je de timer activeert. Deze ontwerpnotitie installeert of start de timer niet. De timer begint opnieuw te tellen nadat de service klaar is; combineer hem met de lock en laat de twee hosts op verschillende momenten controleren.

Dit levert uiteindelijk synchronisatie op, geen atomaire omschakeling tussen hosts. Als één host na rollback tijdelijk op een oudere versie blijft, is dat veiliger dan een slechte image blijven uitrollen om de versies gelijk te trekken. Een lagere prioriteit voor de updater begrenst bovendien niet automatisch de CPU-piek van de Docker-daemon bij het uitpakken van een image; dat moet op de lichte doelhosts worden gemeten.

‘Stil’ betekent hier dat een run zonder update geen applicatie-uitvoer of updategeschiedenis produceert. Systemd kan zelf nog wel gebeurtenissen over de service vastleggen.

Audit, opruimen en acceptatietests

Leg per gebeurtenis de UTC-tijd, hostidentiteit, transactie-ID, oude en nieuwe digest, fase, duur, gezondheidsresultaat en rollbackresultaat vast. Schrijf geen credentials, volledige omgevingsvariabelen, mailaccountgegevens of responsebody’s weg.

Een mogelijk logrotatiebeleid voor de updater is wekelijkse rotatie, eerder roteren boven 1 MB, comprimeren en 26 bestanden bewaren. Dit is een voorstel dat nog moet worden bevestigd; verander hiermee niet stilzwijgend het algemene logbeleid van de host.

Ruim geen images of volumes globaal op. Een wekelijkse opruimtaak mag alleen oude images verwijderen die als eigendom van de updater zijn geregistreerd, en moet dezelfde transactielock gebruiken. Bescherm altijd de huidige versie, de vorige bruikbare versie en alle images die bij een onafgemaakte transactie horen. Controleer ook of een image nog door een bestaande container wordt gebruikt of andere relevante tags heeft.

Voor eigen historische images ouder dan een voorgestelde bewaartermijn van veertien dagen kan het script eerst de eigen bewaartag verwijderen en daarna een niet-forcerende verwijderpoging doen. Lukt verwijderen niet, laat de image staan en registreer dat. Forceer geen verwijdering. Ook een image die ‘dangling’ lijkt, kan handmatig als rollbackmateriaal worden bewaard. Is er vóór het pullen te weinig schijfruimte, breek de update dan af; verwijder niet de enige rollback-image om ruimte te maken.

Voer de implementatie gefaseerd uit:

1. Deployment controleren: verifieer per VPS het platform, de toolversies, projectnaam, configuratiemounts, credentialrechten en de huidige gezonde image. Leg een herstelbare uitgangssituatie vast.
2. Updater bouwen: implementeer digestdetectie, duurzame transactiestatus, omschakeling van één service, gezondheidscontroles, rollback en uitsluiting van mislukte digests. Oefen eerst in een goedgekeurde geïsoleerde omgeving, niet in productie.
3. Planning en beheer toevoegen: configureer de timer, logrotatie en beperkte image-opruiming. Test gelijktijdige runs, time-outs, abnormale beëindiging en herstel na een herstart.
4. Gefaseerd uitrollen: activeer de tweede host pas nadat update én rollback op de eerste host daadwerkelijk zijn getest.

Minimale acceptatietests:

• Digest onveranderd: er worden geen image-lagen opgehaald, geen containers opnieuw aangemaakt en geen updategeschiedenis geschreven. Meet de externe controle en de lokale vergelijking afzonderlijk. Een totale responstijd onder één seconde is alleen een doel dat op de betreffende hosts kan worden gemeten, geen garantie.
• Mailservice blijft ongemoeid: vergelijk vóór en na een geslaagde update of mislukte rollback de container-ID, starttijd en vooraf klaargezette mail van de mailcontainer.
• Rollback werkt: test een defecte image, een niet-200-response, een verlopen gezondheidsvenster en een fout bij het opnieuw aanmaken. Test ook dat rollback lokaal werkt wanneer GHCR niet bereikbaar is.
• Herstel na onderbreking: beëindig de updater op kritieke transactiemomenten en controleer of de volgende start eerst herstel uitvoert en een uitgesloten slechte digest niet steeds opnieuw uitrolt.
• Beveiliging en middelen: controleer dat er niet wordt gebouwd, geen Docker-socket wordt gemount en geen credential lekt. Controleer ook dat maar één update tegelijk loopt en dat opruimen beschermde images intact laat.

Conclusie

Een native updater met vaste image-digests, een duurzame transactiestatus en lokale rollback is een verdedigbare keuze, mits een korte onderbreking van de gateway wordt geaccepteerd, de externe controle als meetdoel in plaats van als harde subsecondengarantie wordt behandeld en de remote configuratie eerst wordt geverifieerd.

De twee VPS’en zijn nog niet gecontroleerd. Compatibiliteit, prestaties onder één seconde en een werkende rollbackketen zijn daarom nog niet aangetoond. Dit is uitsluitend een voorstel voor de implementatie; er is geen ADR aangemaakt en geen bestaand plan overschreven.

De kern: updates op de host, niet in een extra container

Een passende basis is een timer op de host, deployment met een vaste image-digest, duurzame registratie van de update en rollback naar een lokaal bewaarde image. Een aparte updatecontainer is daarvoor niet nodig.

De aanpak is alleen onder voorwaarden haalbaar. Een controle van een externe registry kan niet gegarandeerd iedere keer binnen een seconde klaar zijn. En omdat de gateway als één container opnieuw wordt aangemaakt, zijn nul downtime en verliesvrije afhandeling van lopende verzoeken niet gegarandeerd.

Belangrijk: dit is alleen een ontwerp en implementatiecontract. Er zijn geen bestanden geschreven, tests uitgevoerd of twee externe VPS’en aangepast. Het doel is automatisch herstel bij een mislukte update zolang de host en Docker normaal functioneren. Bij stroomuitval, een niet-beschikbare Docker-daemon of een oude image die zelf niet start, moet het systeem een fout melden; gegarandeerd zelfherstel is dan niet mogelijk.

Wat de huidige configuratie betekent

De releaseworkflow accepteert versietags in de vorm v plus hoofd- en subversie, bijvoorbeeld v3.12. De workflow publiceert latest, 3.12, v3.12 en een korte commit-SHA. Er is geen automatische reeksalias met de naam v3.x. De workflow noemt vier architecturen, maar dat bewijst op zichzelf niet dat iedere release voor al die architecturen succesvol is gepubliceerd (releaseworkflow).

De huidige gatewayservice wordt vanuit broncode gebouwd, luistert op poort 8080 van de host en gebruikt een read-only configuratiemount. De mailservice gebruikt geheugenopslag. De mailcontainer niet opnieuw starten is daarom een harde randvoorwaarde (Compose-configuratie).

De gepubliceerde image start de root-entrypoint. Voor de start is een lokale configuratie voor de modelregistry nodig; die configuratiemap zit niet in de image. Ook na de overstap op een gepubliceerde image moet die configuratie dus op de host beschikbaar blijven (Dockerfile, startcode).

Er zijn bovendien grenzen aan wat een healthcheck kan aantonen. De modelendpoint van de root-entrypoint leest een momentopname van de registry en verstuurt geen echte chatverzoeken. De health-endpoint meldt alleen dat de applicatie leeft. Geen van beide bewijst dat upstreamaccounts zijn opgewarmd of dat een echte chat werkt (modelendpoint, healthroute). Gebruik hierbij niet zomaar de authenticatieregels van een andere handler.

Bij een stopsignaal annuleert de applicatie haar servicecontext; de HTTP-server krijgt vijf seconden om af te sluiten. Een langere Docker-stoptermijn alleen garandeert dus niet dat langlopende streamingverzoeken klaar zijn voordat de container stopt (afsluitlogica).

Buiten de scope: de mailservice aanpassen, accountstatus van een draaiende service synchroniseren, dependencies upgraden, code op afstand ophalen of de lokale ontwikkelbuild veranderen. Ook worden een gelijktijdige omschakeling tussen hosts, nul downtime en verliesvrije afhandeling van lopende verzoeken niet beloofd. Daarvoor zijn onder meer twee instanties, een omschakelbaar toegangspunt en gecontroleerde connection draining nodig.

Zo hoort de updater te werken

Het voorgestelde startpunt is scripts/auto-update.sh; dit script bestaat nog niet. De host heeft onder meer Bash, Docker Engine, de Compose-plugin, curl, jq, flock en Skopeo nodig om alleen de registrymanifesten te lezen. De exacte distributies en versies moeten tijdens de implementatie op de doelhosts worden gecontroleerd.

Laat het script onder een afgeschermd hostaccount draaien en Docker rechtstreeks op de host aanroepen. Mount de Docker-socket of registrycredentials niet in een container. Let wel: een account met Docker-beheerrechten heeft nog steeds ruime macht over de host. Het ontbreken van een socketmount neemt dat risico niet weg.

Werk met digests en duurzame transactiestatus

Gebruik een tag, standaard latest, alleen om te ontdekken of er een nieuwe versie is. Deploy vervolgens altijd een image die is vastgezet op een digest. Compose ondersteunt imageverwijzingen met een digest.1

Houd verschillende identifiers uit elkaar: de digest van het multi-architecturemanifest, de digest van het platformspecifieke manifest en de lokale Docker-image-ID zijn niet onderling uitwisselbaar. Bewaar daarnaast de huidige geaccepteerde image, de vorige werkende image, een eventuele lopende transactie en een registratie van digests die na een mislukking tijdelijk zijn uitgesloten.

Haal vóór een update de image-ID op van de daadwerkelijk draaiende container. Geef die image een eigen lokale bewaartag en controleer eerst of de oude service gezond is. Zo is rollback niet afhankelijk van een nieuwe verbinding met de registry.

Schrijf de status in een strikt gevalideerd gegevensformaat; voer de inhoud nooit uit als shellcode. Schrijf eerst naar een tijdelijk bestand in dezelfde map en vervang het statusbestand daarna atomair. Voor cruciale status moet ook de bestands- en directorystatus duurzaam worden weggeschreven: alleen hernoemen is geen garantie tegen gegevensverlies bij stroomuitval.

Update in gecontroleerde stappen

1. Vraag een vaste bestandslock non-blocking aan. Als een ander proces de lock heeft, stopt deze run stil. Update, herstel, initialisatie en opruimen gebruiken dezelfde lock.
2. Handel een onafgemaakte transactie af voordat je de registry raadpleegt. Controleer het vaste Compose-project, de unieke gatewaycontainer, de configuratiefingerprint en de identiteit van de mailcontainer. Stop bij onverwachte handmatige wijzigingen; neem ze niet automatisch over.
3. Lees alleen de externe manifesten en bereken de juiste digest; download nog geen image-lagen. Bij netwerk-, authenticatie- of parsefouten blijft de huidige service draaien. Een lege digest mag nooit als een nieuwe versie worden behandeld.
4. Is de digest gelijk aan de laatst geaccepteerde versie, dan pullt of herstart het script niets en schrijft het geen updategeschiedenis. Een eerder mislukte digest wordt eveneens overgeslagen totdat er een nieuwe digest is of een beheerder de uitsluiting opheft.
5. Pull de image op basis van de vaste digest. Controleer daarna of de image voor het lokale platform beschikbaar is en of er voldoende schijfruimte is. De oude gateway blijft tijdens het downloaden draaien.
6. Bewaar de oude image en de bijbehorende configuratie en schrijf de fase klaar voor omschakeling duurzaam weg. Maak alleen de gateway opnieuw aan.
7. Controleer de image-identiteit, de containerstatus en de applicatieprobe. Pas na een geslaagde controle wordt de nieuwe versie als geaccepteerd vastgelegd.
8. Mislukt het aanmaken of is de service na het gezondheidsvenster nog niet goed, herstel dan de lokaal bewaarde oude image. Maak alleen de gateway opnieuw aan en voer dezelfde controles uit.
9. Na geslaagde rollback herstel je de duurzame deploymentverwijzing, zet je de mislukte digest op de uitsluitlijst en registreer je de gebeurtenis. Mislukt ook rollback, bewaar dan de herstelbestanden, meld een fout en blijf niet automatisch herstarten.

De volgende shellcommando’s illustreren de richting, maar vormen geen complete of geteste installer. Validatie van de transactie, containeridentiteit en herstel bij onderbrekingen moet nog worden geïmplementeerd:

# Waarden komen uit een gevalideerde configuratie die gewone gebruikers niet kunnen wijzigen.
exec 9>"$LOCK_FILE"
flock -n 9 || exit 0

# Alleen het manifest lezen. Verifieer eerst de authenticatie- en uitvoeropties van Skopeo.
timeout --kill-after=2s 15s \
  skopeo inspect --authfile "$DOCKER_CONFIG/config.json" \
  --raw "docker://$TRACK_IMAGE" \
  </dev/null >"$MANIFEST_TMP"
# Controleer de exitstatus vóór je de digest berekent.
# Verwerk nooit gedeeltelijke uitvoer na een mislukte opdracht.

# NEW_REF moet een gevalideerde ghcr.io-repository@sha256:digest zijn.
timeout --kill-after=5s 600s \
  docker pull "$NEW_REF" </dev/null

# Vooraf zijn de transactie en de lokale rollback-image duurzaam vastgelegd.
APP_IMAGE="$NEW_REF" timeout --kill-after=5s 60s \
  docker compose --project-name "$PROJECT" \
  --project-directory "$DEPLOY_DIR" -f "$COMPOSE_FILE" \
  up -d --no-deps --no-build --pull never app </dev/null

# Bij een fout: OLD_LOCAL_REF is de gecontroleerde, lokaal bewaarde image.
APP_IMAGE="$OLD_LOCAL_REF" timeout --kill-after=5s 60s \
  docker compose --project-name "$PROJECT" \
  --project-directory "$DEPLOY_DIR" -f "$COMPOSE_FILE" \
  up -d --no-deps --no-build --pull never app </dev/null

De Compose-opties voorkomen dat tijdens deze opdracht een build, het starten van afhankelijke services of een extra image-pull plaatsvindt; de opdracht richt zich uitsluitend op app.2 Gebruik geen opdracht die het hele project herstart, wees geen weescontainers of stop alle services.

Een timeout bewijst niet dat een Docker-actie op de achtergrond is beëindigd. Controleer bij zo’n timeout eerst de werkelijke containerstatus en laat herstel pas verdergaan als duidelijk is wat Docker nog uitvoert. Reken bij een harde kill of stroomuitval niet op een exit-trap: herstel moet steunen op de weggeschreven transactie en bij de volgende start voorrang krijgen.

Gezondheidscontrole: wat die wel en niet zegt

Een mogelijke startconfiguratie is een gezondheidsvenster van 60 seconden, een verbindingstime-out van 1 seconde, maximaal 3 seconden per verzoek, een pollinterval van 2 seconden en drie opeenvolgende successen. Dit zijn voorgestelde waarden, geen gemeten resultaten.

• Vraag de lokale modelendpoint op. Vereis HTTP 200, volg geen redirects en controleer de JSON-structuur. Een inlogpagina of proxyfout mag niet als succes tellen.
• Controleer dat de draaiende gatewaycontainer daadwerkelijk de kandidaat-image gebruikt en dat het aantal herstarts niet blijft oplopen. Zo voorkom je dat een oude container ten onrechte een geslaagde controle oplevert.
• Of de modellenlijst niet leeg moet zijn, hangt af van de huidige registryafspraken. Leg geen historisch aantal van achttien items vast als vaste eis.
• Een health-endpoint kan aanvullend zijn, maar start niet automatisch een echte chat die mogelijk quota verbruikt. Echte bedrijfsbeschikbaarheid vraagt om een aparte acceptatietest.

De Compose-configuratie op de VPS

Pas alleen de deploymentkopie op de externe VPS’en aan. Behoud poorten, geheugenlimieten, logging, omgevingsvariabelen, read-only configuratiemounts en de mailconfiguratie. Overschrijf niet de lokale ontwikkelconfiguratie. De image-instelling staat in de gatewayservice (Compose-configuratie).

services:
  app:
    image: "${APP_IMAGE:?Een vastgezette imageverwijzing is verplicht}"
    pull_policy: never

Dit is alleen het te vervangen fragment, niet het volledige Compose-bestand. De deploymentmap moet de complete bestaande servicedefinitie bevatten en de build-instelling van de gateway moet eruit. Bewaar in de deploymentconfiguratie de geaccepteerde digest of de lokale rollbacktag; laat een handmatige herstart niet vanzelf terugvallen op latest.

Controleer ook het bestaande Compose-project en de configuratie op iedere host. Een onverwachte projectnaam kan bijvoorbeeld nieuwe netwerken aanmaken of de verbinding met de mailservice veranderen. Ga er niet van uit dat de projectnaam op de lokale machine gelijk is aan die op beide VPS’en.

Omgevingsvariabelen voor Compose-interpolatie zijn niet automatisch hetzelfde als variabelen in de container. Controleer daarom de bestaande remote instellingen in plaats van aan te nemen dat een omgevingsbestand vanzelf alles doorgeeft. De huidige configuratie schakelt twee experimentele functies expliciet in, terwijl de projectcontext aangeeft dat ze standaard uit horen te staan. Deze taak verandert de schakelaars niet; controleer de waarden op de VPS en neem niet aan dat de lokale configuratie de geïnstalleerde remote versie weergeeft (experimentele instellingen, projectcontext)).

De VPS heeft alleen de deploymentconfiguratie, runtimeconfiguratie en vooraf gebouwde image nodig. Een checkout van de broncode of schrijfrechten op de code-repository zijn niet nodig. Vereist een update een incompatibele configuratiemigratie, dan mag die niet automatisch plaatsvinden zonder een omkeerbaar migratieplan.

Registrytoegang zonder onnodige rechten

Voor een private GHCR-image is een classic personal access token met pakketleesrechten nodig. Controleer of het account bij de image mag en rond, waar vereist, de SSO-autorisatie van de organisatie af. Geef de VPS geen CI-token met schrijfrechten en geen rechten om images of broncode te schrijven of te verwijderen.9

Aanbevolen inrichting:

1. Gebruik per VPS een afzonderlijk, intrekbaar read-only credential. Log in via standaardinvoer, zodat het token niet in argumenten of auditlogs belandt.9
2. Bewaar de Docker-configuratie in een directory voor de updater die alleen door beheerders leesbaar is. Laat de updater en de tool voor manifestinspectie dezelfde, gecontroleerde authenticatieconfiguratie gebruiken.
3. Geef het credential niet door aan de gateway- of mailcontainer. Richt een herinnering voor de vervaldatum en een intrekprocedure in. Bij een authenticatiefout stopt alleen de update; de oude service blijft draaien.

Periodiek uitvoeren met systemd

Systemd is hier de voorkeursoptie. De volgende service- en timerunits zijn voorstellen, geen geïnstalleerde units. Paden en account zijn voorbeelden voor de remote installatie.

[Unit]
Description=Aurora: native image-update en herstel
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=root
WorkingDirectory=/opt/aurora
Environment=DOCKER_CONFIG=/etc/aurora-updater/docker
ExecStart=/opt/aurora/scripts/auto-update.sh
TimeoutStartSec=20min
UMask=0077
Nice=10
IOSchedulingClass=idle
NoNewPrivileges=yes
StandardOutput=journal
StandardError=journal

[Unit]
Description=Aurora: periodieke controle op image-updates

[Timer]
OnBootSec=1min
OnUnitInactiveSec=5min
RandomizedDelaySec=30s
AccuracySec=1s
Unit=aurora-update.service

[Install]
WantedBy=timers.target

Installeer en controleer eerst de dependencies en configuratie. Leg een gezonde oude versie vast en oefen het herstel voordat je de timer activeert. Deze ontwerpnotitie installeert of start de timer niet. De timer begint opnieuw te tellen nadat de service klaar is; combineer hem met de lock en laat de twee hosts op verschillende momenten controleren.

Dit levert uiteindelijk synchronisatie op, geen atomaire omschakeling tussen hosts. Als één host na rollback tijdelijk op een oudere versie blijft, is dat veiliger dan een slechte image blijven uitrollen om de versies gelijk te trekken. Een lagere prioriteit voor de updater begrenst bovendien niet automatisch de CPU-piek van de Docker-daemon bij het uitpakken van een image; dat moet op de lichte doelhosts worden gemeten.

‘Stil’ betekent hier dat een run zonder update geen applicatie-uitvoer of updategeschiedenis produceert. Systemd kan zelf nog wel gebeurtenissen over de service vastleggen.

Audit, opruimen en acceptatietests

Leg per gebeurtenis de UTC-tijd, hostidentiteit, transactie-ID, oude en nieuwe digest, fase, duur, gezondheidsresultaat en rollbackresultaat vast. Schrijf geen credentials, volledige omgevingsvariabelen, mailaccountgegevens of responsebody’s weg.

Een mogelijk logrotatiebeleid voor de updater is wekelijkse rotatie, eerder roteren boven 1 MB, comprimeren en 26 bestanden bewaren. Dit is een voorstel dat nog moet worden bevestigd; verander hiermee niet stilzwijgend het algemene logbeleid van de host.

Ruim geen images of volumes globaal op. Een wekelijkse opruimtaak mag alleen oude images verwijderen die als eigendom van de updater zijn geregistreerd, en moet dezelfde transactielock gebruiken. Bescherm altijd de huidige versie, de vorige bruikbare versie en alle images die bij een onafgemaakte transactie horen. Controleer ook of een image nog door een bestaande container wordt gebruikt of andere relevante tags heeft.

Voor eigen historische images ouder dan een voorgestelde bewaartermijn van veertien dagen kan het script eerst de eigen bewaartag verwijderen en daarna een niet-forcerende verwijderpoging doen. Lukt verwijderen niet, laat de image staan en registreer dat. Forceer geen verwijdering. Ook een image die ‘dangling’ lijkt, kan handmatig als rollbackmateriaal worden bewaard. Is er vóór het pullen te weinig schijfruimte, breek de update dan af; verwijder niet de enige rollback-image om ruimte te maken.

Voer de implementatie gefaseerd uit:

1. Deployment controleren: verifieer per VPS het platform, de toolversies, projectnaam, configuratiemounts, credentialrechten en de huidige gezonde image. Leg een herstelbare uitgangssituatie vast.
2. Updater bouwen: implementeer digestdetectie, duurzame transactiestatus, omschakeling van één service, gezondheidscontroles, rollback en uitsluiting van mislukte digests. Oefen eerst in een goedgekeurde geïsoleerde omgeving, niet in productie.
3. Planning en beheer toevoegen: configureer de timer, logrotatie en beperkte image-opruiming. Test gelijktijdige runs, time-outs, abnormale beëindiging en herstel na een herstart.
4. Gefaseerd uitrollen: activeer de tweede host pas nadat update én rollback op de eerste host daadwerkelijk zijn getest.

Minimale acceptatietests:

• Digest onveranderd: er worden geen image-lagen opgehaald, geen containers opnieuw aangemaakt en geen updategeschiedenis geschreven. Meet de externe controle en de lokale vergelijking afzonderlijk. Een totale responstijd onder één seconde is alleen een doel dat op de betreffende hosts kan worden gemeten, geen garantie.
• Mailservice blijft ongemoeid: vergelijk vóór en na een geslaagde update of mislukte rollback de container-ID, starttijd en vooraf klaargezette mail van de mailcontainer.
• Rollback werkt: test een defecte image, een niet-200-response, een verlopen gezondheidsvenster en een fout bij het opnieuw aanmaken. Test ook dat rollback lokaal werkt wanneer GHCR niet bereikbaar is.
• Herstel na onderbreking: beëindig de updater op kritieke transactiemomenten en controleer of de volgende start eerst herstel uitvoert en een uitgesloten slechte digest niet steeds opnieuw uitrolt.
• Beveiliging en middelen: controleer dat er niet wordt gebouwd, geen Docker-socket wordt gemount en geen credential lekt. Controleer ook dat maar één update tegelijk loopt en dat opruimen beschermde images intact laat.

Conclusie

Een native updater met vaste image-digests, een duurzame transactiestatus en lokale rollback is een verdedigbare keuze, mits een korte onderbreking van de gateway wordt geaccepteerd, de externe controle als meetdoel in plaats van als harde subsecondengarantie wordt behandeld en de remote configuratie eerst wordt geverifieerd.

De twee VPS’en zijn nog niet gecontroleerd. Compatibiliteit, prestaties onder één seconde en een werkende rollbackketen zijn daarom nog niet aangetoond. Dit is uitsluitend een voorstel voor de implementatie; er is geen ADR aangemaakt en geen bestaand plan overschreven.