agiledancers/docs/gitea-ci.md

Gitea build pipeline beheren

De workflow staat in .gitea/workflows/build.yaml. Elke branchpush bouwt en test backend en frontend, bouwt twee images en draait Playwright tegen die containers. Alleen main mag daarna images publiceren. Er vindt geen deployment plaats. Tagpushes en aparte pull-requestevents starten geen extra workflow. Een auteur kan een branchbuild bewust overslaan met een door Gitea ondersteunde markering, zoals [skip ci]; dit is expliciet toegestaan.

Java-bronbestanden uitvoeren

De CI- en setuphulpmiddelen zijn Java 25-bronbestanden. Start ze direct met java ci/Ci.java <opdracht> vanuit de repositoryroot. De Java-launcher compileert de benodigde bronbestanden in het geheugen. Er is geen aparte javac-stap, Maven-module, Python-installatie of scriptingframework nodig. De helper gebruikt alleen de JDK, inclusief de HTTP-client, process builder en bestandsloten.

Beschikbare opdrachten: verify, publish, cleanup, attempt, test, configure-gitea, configure-docker <daemon.json> en install-runner [--prepare-only]. verify heeft een intern tijdsbudget van 75 minuten; publish 15 minuten. Opruimen krijgt een apart budget van 2 minuten.

Zorg dat java naar JDK 25 verwijst, bijvoorbeeld met:

export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
export PATH="$JAVA_HOME/bin:$PATH"

Machines en voorwaarden

Gitea 1.25.4 en de registry staan op de bestaande Synology, http://192.168.2.28:3000. De runner draait als gebruikersservice op de bestaande Linux x86_64 mini-pc. Er is geen extra hardware nodig. De mini-pc moet aanstaan en wakker blijven; Docker en de runner moeten draaien. Anders blijven jobs wachten. Een host-runner voert repositorycode uit als de ontwikkelgebruiker: gebruik deze runner alleen voor deze vertrouwde repository.

De runner heeft Git, Bash, JDK 25, Maven 3.9+, Node 22.22.3+/24.15.0+/26+, npm en een werkende Docker-daemon nodig. De huidige mini-pc heeft de ontwikkeltools en Docker Desktop al geïnstalleerd. De workflow gebruikt één job tegelijk (capacity: 1), één Playwright-worker en CPU/geheugenlimieten voor de tijdelijke applicatie- en browsercontainers.

Doelarchitectuur eerst vaststellen

Controleer op de Synology via een bestaande beheerverbinding:

uname -m
docker info --format '{{.OSType}}/{{.Architecture}}'

x86_64/amd64 betekent linux/amd64; aarch64/arm64 betekent linux/arm64. Leg de werkelijke uitvoer, datum en het Synology-model vast bij de oplevering en stel repositoryvariabele TARGET_PLATFORM daarop in. De workflow weigert een ontbrekende waarde en een verschil met de Docker-daemon van de runner; hij doet dus geen stilzwijgende aanname over de NAS en gebruikt geen ongeteste emulatie. Een mismatch vereist een geteste oplossing op de bestaande machines voordat S4 afgerond kan worden; er worden geen multi-architecture images gebouwd.

Docker op de mini-pc

Start de al aanwezige Docker Desktop via de desktop of:

systemctl --user start docker-desktop
docker --context desktop-linux info

Bij Docker Desktop configureer je onder Settings → Docker Engine de inhoud van ci/runner/docker-daemon.json, samengevoegd met bestaande instellingen. Je kunt de instelling ook samenvoegen met behoud van bestaande instellingen en backup via:

java ci/Ci.java configure-docker "$HOME/.docker/daemon.json"

Voor Docker Engine op Linux is dat dezelfde toevoeging aan /etc/docker/daemon.json (met de daarvoor benodigde beheerrechten). Overschrijf geen andere daemoninstellingen. Pas de wijziging toe/herstart de daemon en controleer met docker info dat 192.168.2.28:3000 onder de insecure registries staat. Configureer ook andere Docker-clients die images van deze interne HTTP-registry moeten ophalen.

Gebruik de Docker Desktop-context of zet DOCKER_HOST expliciet. De installer neemt de geselecteerde socket over in de gebruikersservice. Als de socket later wijzigt, pas dan ~/.config/agiledancers-runner/environment aan en herstart de runner. Bij Docker Desktop blijft de Desktop-VM eveneens nodig voor builds. Runner en containers moeten de Synology en internetdownloads kunnen bereiken.

Gitea-instellingen en credentials

Repository: wanjakrah/agiledancers, hoofdbranch: main. Actions staat voor deze repository al aan. Controleer zo nodig op de Synology app.ini onder [actions] de instelling ENABLED = true en de Actions-feature onder repositoryinstellingen. De standaard SKIP_WORKFLOW_STRINGS, waaronder [skip ci], mogen blijven staan: bewust overslaan is door de maintainer toegestaan. Iedere gewone branchpush start een pipeline. Er hoeft daarvoor geen serverinstelling te worden gewijzigd.

Stel bij repository Settings → Actions in:

Soort	Naam	Waarde/doel
Variabele	TARGET_PLATFORM	Vastgestelde Synology-platformwaarde
Secret	REGISTRY_USER	Gitea-gebruiker die in namespace wanjakrah mag publiceren
Secret	REGISTRY_TOKEN	PAT met write:package en read:repository voor imagepublicatie en controle van de huidige hoofdbranch

Het gewone jobtoken van Gitea 1.25 biedt geen packagepublicatie; gebruik een PAT. Gebruik een repository-runnerregistratietoken, geen instancebrede registratie. Sla tokenwaarden buiten Git op en plaats ze niet in opdrachten, screenshots of logs.

Voor reproduceerbare configuratie bestaat java ci/Ci.java configure-gitea. Maak twee bestanden buiten de repository met mode 600: één voor een PAT met voldoende repositorybeheerrechten (repository Actions, secrets, variabelen en runnerregistratie), en één voor de publicatie-PAT. De beheer-PAT hoeft niet als workflowsecret te worden bewaard. Vul die bestanden via een lokale editor of verborgen terminalinvoer. Voer daarna uit met de werkelijke platformwaarde:

export GITEA_ADMIN_TOKEN_FILE="$HOME/.config/agiledancers-runner/admin-token"
export REGISTRY_TOKEN_FILE="$HOME/.config/agiledancers-runner/registry-token"
export REGISTRY_USER=wanjakrah
export TARGET_PLATFORM=linux/amd64  # alleen als dit op de Synology is vastgesteld
java ci/Ci.java configure-gitea

Het script stelt de repository-instellingen in via de API en schrijft het runnerregistratietoken naar ~/.config/agiledancers-runner/registration-token met mode 600. Het toont geen tokenwaarden. Voor handmatige inrichting kun je dat registratietoken uit de repository-instellingen halen en in hetzelfde bestand plaatsen.

De bevestigde Gitea 1.25.4-configuratie heeft geen [actions]-sectie: de defaults zijn negentig dagen voor artifacts en 365 dagen voor logs. Een workflow vraagt veertien dagen via retention-days: 14. Een kortere serverlimiet of het vroegtijdig verwijderen van workflowruns mag die periode niet inkorten. Artifactretentie geldt voor testdiagnostiek; gepubliceerde containerimages worden niet automatisch verwijderd.

Runner installeren en starten

export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
java ci/Ci.java install-runner --prepare-only
# Na Dockerconfiguratie en het opslaan van het registratietoken:
java ci/Ci.java install-runner
systemctl --user status agiledancers-runner
journalctl --user -u agiledancers-runner -f

De installer controleert tools, installeert checksum-gecontroleerde runner v0.2.13, neemt label agiledancers-mini-pc:host over en registreert de runner. Configuratie en .runner-credentials staan in ~/.local/share/agiledancers-runner, de service in ~/.config/systemd/user/agiledancers-runner.service en de expliciete Java-, PATH- en Docker-socketinstellingen in ~/.config/agiledancers-runner/environment. Een bestaande registratie wordt hergebruikt. Er worden geen secrets in de repository geschreven. Bewaar het tokenbestand alleen zolang registratie/herstel dat nodig heeft en behandel .runner als credential.

Op de mini-pc starten Docker Desktop en de runner automatisch na grafisch aanmelden. Bij een Docker Desktop-socket installeert de installer hiervoor ~/.config/systemd/user/agiledancers-runner.service.d/10-agiledancers-docker-desktop.conf en schakelt beide services in voor graphical-session.target. De runner wacht via ~/.local/share/agiledancers-runner/WaitForDocker.java maximaal 120 seconden tot de ingestelde Docker-engine bereikbaar is. Bij een mislukte start probeert systemd het na tien seconden opnieuw. De runner volgt stoppen en herstarten van Docker Desktop en stopt bij afmelden.

User lingering staat op deze pc uit: vóór aanmelden starten deze services niet. S4 belooft geen beschikbaarheid wanneer de mini-pc uitstaat. Herstarten/stoppen:

systemctl --user restart agiledancers-runner
systemctl --user stop agiledancers-runner

Images en publicatie

Component	Image
Backend	192.168.2.28:3000/wanjakrah/agiledancers-backend
Frontend	192.168.2.28:3000/wanjakrah/agiledancers-frontend

De volledige commit-SHA is de versie van beide images. Een main-tag wijst naar de nieuwste met succes gepubliceerde actuele hoofdbranchbuild. Gebruik voor een exact passend paar op beide images dezelfde SHA:

# Gebruik bij private packages eerst docker login met interactieve invoer.
commit_sha=<volledige-commit-SHA>
docker pull "192.168.2.28:3000/wanjakrah/agiledancers-backend:$commit_sha"
docker pull "192.168.2.28:3000/wanjakrah/agiledancers-frontend:$commit_sha"

De frontend luistert op containerpoort 8080, ondersteunt SPA-routes en proxy't /api/ naar BACKEND_UPSTREAM (standaard backend:8080). De backend luistert op 8080. Voorbeelden voor eventueel handmatig starten staan los van de pipeline; de pipeline start geen blijvende applicatie op de NAS.

java ci/Ci.java verify maakt een succesmarker pas na alle builds en tests. java ci/Ci.java publish vereist die marker en hoofdbranchref. Onder een gedeeld Java-bestandslot (FileChannel) buiten de checkout worden bestaande commitimages hergebruikt en ontbrekende images geüpload. Iedere image wordt teruggehaald, op revisielabel gecontroleerd en met digest vastgelegd in de diagnostiek. Authenticatie- of netwerkfouten tellen niet als een ontbrekende tag.

Pas na beide images worden main-tags bijgewerkt, met een actuele hoofdbranch- controle voor iedere wijziging. De gedeelde lock voorkomt dat een oudere pipeline een door een nieuwere pipeline bijgewerkte tag terugzet. capacity: 1 ondersteunt dat op de enige runner. Vertrouw niet op workflow-concurrency: Gitea 1.25 negeert die instelling. De twee bewegende tags zijn geen atomisch paar.

Diagnostiek en herstellen

Iedere workflowpoging bewaart beschikbare diagnostiek als diagnostics-<run-id>-<unique-attempt-id> gedurende veertien dagen: Maven-rapporten, JUnit- rapporten van frontend/Playwright, het Playwright HTML-rapport, traces/screenshots en containerlogs. Open de artifactdownload op de Gitea Actions-runpagina. Build- en publicatielogs staan er eveneens in. Gitea 1.25 vult gitea.run_attempt niet in; de workflow maakt daarom zelf een unieke identificatie per poging. Geen environmentdump of Docker inspect met mogelijke credentials wordt opgenomen.

Bij mislukking blijven de oorspronkelijke exitstatus en rapporten behouden. Een Java-finally/shutdown-hook én een always()-stap verzamelen diagnostiek en verwijderen de tijdelijke containers en het netwerk met hun unieke runnaam. Een harde machine-uitval kan opruimen onderbreken: controleer daarna uitsluitend achtergebleven resources met label agiledancers.ci.run; gebruik geen algemene Docker-prune op de ontwikkel-PC.

Herstart een mislukte run vanuit Gitea. Als slechts één commitimage gepubliceerd was, bewaart de herhaling die en vult de ontbrekende image aan. Een fout bij publiceren, terughalen of bijwerken van main laat de pipeline falen. Bestaande commitimages worden niet overschreven. Bij een inmiddels nieuwere hoofdbranch blijven de committags bruikbaar en worden de oude main-updates overgeslagen.

Lokale controle van publicatie-/foutgedrag zonder registrywijzigingen:

java ci/Ci.java test

Volledige lokale verificatie met Docker en de vastgestelde platformwaarde:

export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
export TARGET_PLATFORM=linux/amd64  # eerst de Synology controleren
java ci/Ci.java verify

Operationele oplevering

Leg links/run-ID's en beide image-digests vast in docs/s4-validation.md voor:

1. Een geslaagde feature-branchpush, inclusief twee builds en container-E2E, zonder imagepublicatie.
2. Een expres mislukte build/test op een tijdelijke branch die publicatie blokkeert, met downloadbare foutdiagnostiek. Herstel die testwijziging daarna.
3. Een geslaagde hoofdbranchrun met beide teruggehaalde commitimages.
4. Een herhaling/partiële-publicatieherstel en bewijs dat bestaande committags behouden blijven en oudere builds main niet terugzetten.

Zonder werkende runner, vastgestelde NAS-architectuur, registrytoegang en echte pipelinebewijzen is S4 niet volledig opgeleverd.

Bronnen: runner, Gitea-verschillen, containerregistry.