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. Deze buildworkflow voert geen deployment uit. S6 voegt aparte handmatige workflows toe voor productie en rollback; zie productiedeployment. 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 generated/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 de vertrouwde repositories van deze eigenaar.

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 generated/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/mini-pc-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 de gedeelde user-scoped runner mini-pc voor wanjakrah; een nieuwe repository heeft geen eigen runnerregistratie nodig. Sla tokenwaarden buiten Git op en plaats ze niet in opdrachten, screenshots of logs.

Voor reproduceerbare configuratie bestaat java generated/ci/Ci.java configure-gitea. Maak twee bestanden buiten de repository met mode 600: één voor een PAT met voldoende repositorybeheerrechten (repository Actions, secrets en variabelen), 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 generated/ci/Ci.java configure-gitea

Het script stelt alleen de applicatie-instellingen, registrysecrets en platformwaarde in. De gedeelde runnerregistratie wordt eenmalig beheerd vanuit engineering. Applicatiespecifieke deploymentcredentials blijven onder ~/.config/agiledancers-runner/.

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.

Gedeelde runner gebruiken

De fysieke mini-pc draait mini-pc-runner.service met label mini-pc:host, geregistreerd op gebruikersniveau voor wanjakrah. Daardoor kunnen bestaande en nieuwe repositories van deze eigenaar dezelfde runner gebruiken. De gedeelde capaciteit is één job tegelijk. De workflowbestanden gebruiken runs-on: mini-pc.

Voor eenmalige registratie, installatie en migratie volg je de engineering-instructies. Controleer dit project met java generated/ci/Ci.java check-runner; gebruik daarbij het in engineering beschreven owner-only tokenbestand voor de gedeelde setup.

systemctl --user status mini-pc-runner
journalctl --user -u mini-pc-runner -f
systemctl --user restart mini-pc-runner

Runnerstate staat onder ~/.local/share/mini-pc-runner/ en serviceconfiguratie onder ~/.config/mini-pc-runner/. De runner start samen met Docker Desktop na grafisch aanmelden, wacht maximaal 120 seconden op Docker en probeert een mislukte start opnieuw. User lingering staat uit: vóór aanmelden of bij een uitgeschakelde mini-pc is de runner niet beschikbaar. De oude agiledancers-runnerstate blijft voor herstel bewaard; applicatiespecifieke deploymenttokens en SSH-sleutels blijven op hun eigen paden.

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 generated/ci/Ci.java verify maakt een succesmarker pas na alle builds en tests. java generated/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 generated/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 generated/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.